Skip to content
dmsforall

API reference

The web interface is a client of the public API. Anything you can do in the interface, you can do with the API.

Base address and versions

Section titled “Base address and versions”

All endpoints are under /api/v1/, for example https://garage.example.org/api/v1/sante. The version is part of the path.

OpenAPI description

Section titled “OpenAPI description”

The API publishes an OpenAPI description, generated from the code. It is served only when OPENAPI_EXPOSER_DOCS=true:

  • /api/docs: interactive documentation;
  • /api/docs.json: the OpenAPI document, for code generation.

Keep it disabled on a production server that is reachable from the Internet, unless you need it. To produce the document from a source checkout, run pnpm api:openapi.

Sign in

Section titled “Sign in”

Signing in creates a session cookie. Send the cookie with each request. The cookie name is dfa_session by default.

EndpointMethodUse
/api/v1/auth/connexionPOSTSign in with an e-mail address and a password.
/api/v1/auth/deconnexionPOSTSign out and close the session.
/api/v1/auth/moiGETReturn the signed-in user and their rights.
/api/v1/auth/mot-de-passe/oubliPOSTAsk for a password reset e-mail.
/api/v1/auth/mot-de-passe/reinitialisationPOSTSet a new password with the reset token.

Example with curl. The Origin header is required by the CSRF protection.

Terminal window
curl -c cookies.txt \
  -H "Origin: https://garage.example.org" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","motDePasse":"replace-me"}' \
  https://garage.example.org/api/v1/auth/connexion

Check the exact body of the sign-in request in the OpenAPI description, which is the reference.

Lists and pagination

Section titled “Lists and pagination”

Lists use cursor pagination:

  • limite: number of items to return.
  • curseur: the cursor to get the next page. Take it from the field curseurSuivant of the previous response. Do not build cursors yourself.

A list response has three fields: donnees (the items), curseurSuivant (the next cursor, or null on the last page) and limite.

Errors

Section titled “Errors”

Errors use the application/problem+json format. Read the status and the type fields first. A request that the role does not allow returns 403 with the code DROIT_INSUFFISANT.

Other conventions

Section titled “Other conventions”
  • Amounts are integers in centimes. 1'234.50 CHF is sent as 123450.
  • Sensitive creations accept an idempotency key, so that a retry does not create a duplicate.
  • Dates and times use ISO 8601.