CMS
Store legal pages, UI translations, release notes and your own content in the Ovok CMS, and read it from your apps with the public delivery API.
The Ovok CMS holds the content your app needs that FHIR does not model: legal pages, UI translations, release notes and content types you define yourself. You write it once in the Ovok Console, and your apps read the published version over a public, cacheable API.
What you can read
| Collection | What it holds | Who may read it |
|---|---|---|
legal-pages | Terms, privacy and similar pages, with a localised title and body. | Anyone who names your tenant code. |
translations | UI text, one document per group, with a localised value for each key. See Use Ovok CMS with i18n. | Anyone who names your tenant code. |
release-notes | Release notes, with tags and a publish date. | A CMS API key, or a signed-in user of your project. |
posts | Blog posts, with a localised title, excerpt and rich-text body, a publish date and a slug. | A CMS API key, or a signed-in user of your project. |
| Your own content types | Items you define in the Console. | A CMS API key, or a signed-in user of your project. |
Ovok decides which collections are open to anyone; an operator can change that list for a deployment.
The routes
| Route | Page |
|---|---|
GET /v1/public/cms/collections/:collection/items | List the items of a collection |
GET /v1/public/cms/collections/:collection/items/:slug | Get an item by slug |
GET /v1/public/cms/:contentTypeSlug/items | List the items of a content type |
| Use Ovok CMS with i18n |
Enable the CMS
CMS enablement is managed for the tenant in the Ovok Console. The Console records the resulting state in the CONTENT_ENABLED project setting and manages authoring access and billing. Setting that marker through the project settings API does not enable or disable the complete CMS workflow, and the public-delivery routes do not read it.
- 1CONTENT_ENABLED shows whether CMS is enabled for this tenant.
- 2Open CMS and choose a collection after it is enabled.
- 3Create the first post with a title and a unique slug.
Your project's content space is created the first time the Console or an app uses the CMS. It needs your project's tenant code, and a brand-new code can be refused as unknown for up to a minute.
Tenants
Content belongs to a tenant: your project, named by its tenant code. The sandbox and production do not share content, so write it on the API your app reads.
| You send | Where | Meaning |
|---|---|---|
tenant | Query, or the x-ovok-tenant-code header | Your tenant code. |
projectId | Query | Your project's id, a UUID. Use it when you do not have the tenant code. A tenant code takes precedence if both are sent, but the project ID must still be a valid UUID. |
- Name the tenant on every read. A signed-in user may leave it out and reads their own project; anyone else gets
400. - Headers beat query values, even empty ones. An empty
x-ovok-tenant-codeheader hides?tenant=.
Who can read content
Three ways in, tried in this order:
| Way | How | Reads |
|---|---|---|
| A CMS API key | x-api-key: <key>, Authorization: Bearer <key> or ?apiKey=<key>, plus the tenant | Published content of the key's own project. |
| An open collection | Nothing. Only the tenant code. Applies to legal-pages and translations by default, and only on the collection routes. | Published content of the tenant you name. |
| A signed-in session | An Ovok access token as Authorization: Bearer <token> | Published content of the user's own tenant only. |
Anything else answers 401.
- A key reads only its own project's tenant. A request with a key must name the tenant; a key of another project answers
401. See API keys. - Keep keys on your server, not in a browser or mobile app. Use an open collection or a signed-in session there.
- A session that names another tenant gets
403, not401, so the SDKs do not sign the user out. The exception is an open collection: a signed-in user can read another tenant'slegal-pagesortranslationsby naming it. - Authentication comes before everything else.
GET .../collections/users/itemswithout a key answers401, even though no such collection is served.
API keys
Each project has its own CMS API keys. A project admin manages them in the Console on the CMS page, under CMS API keys:
- 1Create a CMS API key for the website.
- 2Copy the one-time key, then revoke it when access is no longer needed.
-
A new key is shown once. Copy it then; Ovok cannot show it again.
-
Each key shows its name, a short prefix and when it was made, never the key itself.
-
Every project starts with a Default key. Revoke it once your apps use keys of their own.
-
At most 20 keys per project, the default included. A 21st answers
409. -
Revoking takes effect at once, but a response a CDN already cached is served until it expires; see caching.
-
Ovok stores only a hash of each key.
Languages
The CMS has every ISO 639-1 language as a bare two-letter code, 183 in all, such as de, it or zh. en is the default. Pass locale=it.
- A malformed tag answers
400:en_US,DEandallare refused. - Use the bare codes. A tag such as
de-DEis accepted, but the CMS does not have it and answers in English. - The Ovok SDKs read four of them. They map
de-DEtodefor you, but only forde,en,frandes; any other app language is read asen. For another language, call the API with the bare code yourself, as in Use Ovok CMS with i18n. - A text or textarea field with no value in the language falls back to English field by field.
Published content
Only documents with status published are returned. A draft, and a document that does not exist, look the same: not found. There are no versions or scheduled publishing: publishedAt is an ordinary date and hides nothing.
Rich text is returned as the editor's JSON structure, not as HTML.
Shared content
Ovok keeps a shared tenant of its own, which contributes documents to every tenant:
- On the list routes, its published documents are merged with yours.
- On the get-by-slug route, it is the fallback when your tenant has no document with that slug.
- Your document wins when the slug is the same. A
translationsgroup of yours replaces the shared group of the same slug whole, so a group with one key hides the shared group's other keys. - The merge is skipped when either side has more than 200 published documents, and your own list is returned unmerged.
- A failing shared read never breaks your read: you get your own documents.
Caching
| Response | Cache-Control |
|---|---|
| A tenant named by code or project id | public, s-maxage=60, stale-while-revalidate=300 |
| A signed-in user who names no tenant | no-store |
| An error | None |
A tenant-named response also carries a Vary header on the tenant, project, API key and Authorization headers. Ovok caches each read for about 60 seconds, so an edit shows up within a minute, plus up to about 5 minutes more behind a CDN. Nothing purges the cache when you publish.
Browsers and CORS
For an allowed origin, Ovok's CORS policy accepts Content-Type, Authorization, Accept-Language, If-Match, X-Ovok, X-Tenant-Code and the tracing headers. x-api-key and x-ovok-tenant-code are not allowed, so a browser must send:
- the key as
Authorization: Bearer <key>or?apiKey=; - the tenant as
?tenant=.
A key in the URL can end up in logs. Prefer the header from a server.
Limits
| What | Value |
|---|---|
page | 1 to 100. A non-number falls back to 1. |
limit | 1 to 50. Default 20. |
| Documents readable per list | 5,000 (50 per page, 100 pages) |
| Content type route | At most 100 items, no paging, no sort, no locale |
| Slug | Lower-case letters, digits, -, _ and .; starts with a letter or digit; up to 128 characters |
| Usage | Public CMS reads do not count towards your project's API usage statistics or your plan's request cap. |
| Rate limit | Key-only and unauthenticated calls use the unknown-caller limit: 1,000 per minute per route and IP address. Signed-in calls use the caller's role limit per route: patients and related people 100 per 30 seconds; practitioners 200 per 30 seconds; admins and client applications 1,000 per 30 seconds. Over a limit returns 429. |
Errors
| Status | message | Cause |
|---|---|---|
400 | Public CMS delivery requires a tenant code, a project id, or a signed-in session | No tenant is named and the caller is not signed in. |
400 | Unknown tenant code: <code> | The tenant code does not exist. |
400 | Invalid project id. followed by what was expected | projectId is not a UUID. |
400 | Invalid locale "<value>". Expected a language tag like "de" or "en-US". | The language tag is malformed, or is all. |
400 | Invalid sort "<value>". Expected a field name, optionally prefixed with "-". | sort is not a top-level field name. |
400 | Public CMS delivery with an API key requires a tenant | A request with a key named no tenant. |
401 | Invalid or missing CMS public API key | The collection is not open and there is no valid key or session, or the key belongs to another project or was revoked. |
403 | A signed-in session reads its own tenant's content | A signed-in user named another tenant. |
404 | Not found | A missing, unpublished or malformed slug, or a collection that is not served. |
429 | Too Many Requests | Over the rate limit. Wait retryAfterSec seconds (the Retry-After header). |
502 | Unable to resolve the CMS tenant | The CMS is unreachable. Retry. |
Errors share the format in errors and troubleshooting; a 429 body also has retryAfterSec. See the rate-limit headers. A CMS failure is never answered with an empty 200.
Related
Last updated on