The endpoints

What this is about

CRMS offers its functions over HTTP, all under the path /crms. This is done by the CRMS HTTP interface. It is an adapter: it reads a request, calls the matching function of a CRMS module and writes the response. It has no business logic of its own.

Where the routes run

The routes exist where CRMS runs embedded, meaning in the same process as the application, and the CRMS HTTP interface is on the classpath. The separate CRMS service always brings it along.

In the remote operating mode the application would otherwise pass the CRMS service on under its own routes, behind its own security. That is why the start refuses the HTTP interface there. More on the operating modes in Embedded or standalone.

The path of a request

The HTTP interface reads no token itself. The person comes through CIAS, see The roles.

Rendering

Rendering needs no role of its own. It is enough to be signed in and to be allowed to see the template. Which template a request finds is described in How a template is found, the fields of the request in The render request.

POST /crms/render
Content-Type: application/json

{ "template": "audit-report", "format": "PDF", "mode": "FINAL",
  "reference": "audit-4711", "locale": "de-DE",
  "data": { "customer": { "name": "ACME" } } }

200
Content-Type: application/pdf
Content-Disposition: inline; filename="audit-report.pdf"
Crms-Template-Key: audit-report
Crms-Template-Scope: TENANT          ← which edition won
Crms-Template-Variant: de-DE         ← which language variant
Crms-Template-Revision: 3f1c…        ← which revision of the template
Crms-Template-Revision-Hash: sha-256:…
Crms-Document-Revision: 9a7e…        ← with FINAL only
X-Content-Type-Options: nosniff

<the bytes of the PDF>

/crms/render/validate checks the same request without rendering. GET /crms/capabilities names the formats, the default PDF profile, the admitted scopes, the languages, whether final documents are stored (documentRevisions), whether transient documents are allowed (transientDocuments), and the limits (timeout, maxOutputBytes, maxPayloadBytes, maxAttachmentCount, maxAttachmentBytes).

Templates

A template editor uses these routes. Each route calls exactly one function of the template module. See means: the template belongs to the system, to your tenant or to you. Write means: in addition, the write role of the edition’s scope. Review means: the role of the current approval stage.

A few rules apply to all template routes:

• A draft is always saved whole. content replaces the old content, with source, fields and all assets as Base64. Base64 is a notation that writes bytes as text.
• expectedVersion is the version of the draft your change builds on, 0 for none. If someone else saved in the meantime, CRMS answers 409 template-draft-changed.
• Whether a reason is required is decided by the installation. When rejecting, it is always required.
• The body is limited, 16 MiB by default, adjustable through CODAMAI_CRMS_REST_TEMPLATE_MAX_BYTES. Above that: 413 request-too-large|<limit>.
• Assets come as a download (Content-Disposition: attachment) with X-Content-Type-Options: nosniff and Content-Security-Policy: sandbox. This way an SVG cannot run scripts on the application’s page in the browser.

The whole flow from draft to publication is described in The life cycle of a template and Approval.

Documents

These routes work with final documents. The archive checks the role before it looks anything up, the same as for an embedded call.

• When listing, all three parameters are required. If one is missing, you get 422 validation-failed with the rule required.
• The three changing routes need a body {"reason": "litigation-hold"}. The reason is a key in kebab-case, not free text, because it ends up in a chain that is never deleted. Free text gives 422 validation-failed.
• Reading returns the whole description of the revision in headers: Crms-Document-Revision, Crms-Document-Number, Crms-Document-Format, Crms-Document-Stored-At, Crms-Document-Retain-Until, Crms-Document-Legal-Hold, Crms-Document-Content-Hash and the Crms-Template-* headers as when rendering.
• The archive always works in the tenant of the person asking and records them as the actor.

What verify, legal hold and erase mean in practice is described in Verify and export and Retention, legal hold and erasure.

Rules for all routes

Pitfalls

Next

• The roles
• The error answer
• The client for a separate service