{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Conventions","siteUrl":"https://docs.api.dentally.com"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"conventions","__idx":0},"children":["Conventions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are the conventions you can rely on across every operation in the"," ","contract. They are enforced by the spec; if you spot a deviation, please"," ","report it to the APIs & Partnerships team — it is a bug."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transport","__idx":1},"children":["Transport"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTPS"]}," in deployed environments."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JSON"]}," for request and response bodies (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json; charset=utf-8"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP semantics"]}," are honoured: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," is safe and idempotent, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4XX"]}," is a"," ","client error, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5XX"]}," is a server error. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/pages/errors"},"children":["Errors"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"urls-and-identifiers","__idx":2},"children":["URLs and identifiers"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A fixed major prefix ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v2"]},". Dated revisions are selected by header — see"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/pages/versioning"},"children":["Versioning"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Resource collections are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["plural nouns"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/patients"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/sites"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/practitioners"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["IDs are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["strings"]}," carrying UUIDs (RFC 4122):"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3fa85f64-5717-4562-b3fc-2c963f66afa6"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"field-naming","__idx":3},"children":["Field naming"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Field names are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["snake_case"]}]}," (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address_line_1"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email_address"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Header names follow HTTP conventions (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Practice-Id"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Dentally-API-Version"]},")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"dates-and-times","__idx":4},"children":["Dates and times"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All timestamps are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ISO 8601 in UTC"]},", with the trailing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Z"]},":"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2025-08-12T11:00:00Z"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Time‑of‑day fields without a date use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HH:MM"]}," (24‑hour) in the local time"," ","of the resource (for example a site's opening hours)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Calendar dates without a time use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"nullability","__idx":5},"children":["Nullability"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fields that are ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["known to be absent"]}," are returned as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," rather than"," ","omitted (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address.address_line_2: null"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["opening_hours[].open_at: null"]}," ","for a closed day)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Required fields per the schema are always present."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-envelopes","__idx":6},"children":["Response envelopes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Single resource:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"data\": { /* one object */ } }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List resource (always paginated):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": [ /* array of objects */ ],\n  \"meta\": { \"cursor\": \"<opaque or null>\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/pages/pagination"},"children":["Pagination"]}," for cursor handling."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"required-headers","__idx":7},"children":["Required headers"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When"},"children":["When"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <jwt>"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["every request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/pages/authentication"},"children":["Authentication"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Dentally-API-Version: <id>"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["recommended on every request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/pages/versioning"},"children":["Versioning"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Practice-Id: <uuid>"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["practice‑scoped operations"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identifies the practice the request acts on."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"errors","__idx":8},"children":["Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every non‑2xx response is a Problem Details body"," ","(",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc7807"},"children":["RFC 7807"]},"). See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/pages/errors"},"children":["Errors"]}," ","for the full envelope and standard responses."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"forward-compatibility","__idx":9},"children":["Forward compatibility"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["New, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," request fields and headers may be added within a dated"," ","version. Reject unknown fields client‑side at your peril."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["New response fields may be added within a dated version. Clients ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"," ","ignore unknown response properties"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Breaking changes only ever ship as a new dated version — see"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/pages/versioning"},"children":["Versioning"]},"."]}]}]},"headings":[{"value":"Conventions","id":"conventions","depth":1},{"value":"Transport","id":"transport","depth":2},{"value":"URLs and identifiers","id":"urls-and-identifiers","depth":2},{"value":"Field naming","id":"field-naming","depth":2},{"value":"Dates and times","id":"dates-and-times","depth":2},{"value":"Nullability","id":"nullability","depth":2},{"value":"Response envelopes","id":"response-envelopes","depth":2},{"value":"Required headers","id":"required-headers","depth":2},{"value":"Errors","id":"errors","depth":2},{"value":"Forward compatibility","id":"forward-compatibility","depth":2}],"frontmatter":{"seo":{"title":"Conventions"}},"lastModified":"2026-05-06T00:53:10.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/pages/conventions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}