An integration written against the API today should still work tomorrow. This page describes what a partner application can rely on — and what it needs to handle gracefully in return.
The major version is part of the URL
https://<tenant>.stp-cloud.de/documents/dms-cloud-api/api/v1/dms/documents/container
^^
Major version- The major version appears in every URL. It is the only thing that can force a change on the partner side.
- There is no minor version in the URL. Backwards-compatible additions are released within the same major version, with no action required from the partner application.
- There is no header-based negotiation. The URL is the way.
What may change within a major version
The following changes may occur without prior notice and without a new major version:
| Change | Why it's safe |
|---|---|
| A new endpoint is added | If you don't call it, nothing changes |
| An optional field is added to a request | Existing calls simply omit it, and behavior remains unchanged |
| A field is added to a response | Requires that unknown fields are ignored |
| An optional query parameter is added | Same as an optional request field |
| A new value appears in an enumeration | Requires that unknown values are handled gracefully |
| A new error code appears | Requires that unknown codes are handled gracefully |
| A validation rule is relaxed | Calls that previously met the stricter rule will continue to work |
| An optional response header is added | If you don't read it, nothing changes |
The three requirements for partner applications
The table above implies three requirements for every integration. These are not recommendations — they are prerequisites for any integration to remain functional over time:
- Ignore unknown fields in responses — don't abort, and don't log them as errors.
- Handle unknown enumeration values gracefully — use a sensible fallback instead of throwing an exception.
- Handle unknown error codes gracefully — make decisions based on the HTTP status, as described in Error Codes.
What requires a new major version
| Change | Why it's breaking |
|---|---|
| A field is removed | Existing code that reads it will stop working |
| A field is renamed | Equivalent to removing and adding a field |
| The data type of a field changes | Existing parsing logic will fail |
| The meaning of a field changes | The worst case — it breaks silently |
| A previously optional field becomes required | Existing requests will fail validation |
| An enumeration value is removed | State machines on the partner side will break |
| An endpoint is removed | Immediate breakage |
| The URL structure changes | Resources can no longer be found |
| The pagination mechanism changes | Iteration over result lists will break |
| The meaning of an existing error code changes | Retry logic will break silently |
What applies when moving to a new major version
When a new major version is released, the old one doesn't disappear overnight — both versions run in parallel for a period of time, so that migration can be planned rather than forced.
The specifics of this transition will be defined by STP at the relevant time and communicated to the affected partners and law firms. This page intentionally does not mention any deadlines, dates, or notice periods: by the time you read this, they may well be out of date, and what applies to you will depend on your contractual agreement with STP.
There are two things you can count on:
- There will be no silent shutdowns. Any transition will be announced before it takes effect.
- A deprecated version should also be identifiable programmatically. The plan is to include appropriate indicators in response headers, so that an integration can detect this and alert its own operations team without relying on an email. As long as there is only one major version, this remains a statement of intent rather than something you can build logic around.
Deprecation of individual fields
Sometimes a field needs to be retired without requiring a new major version. The process is as follows:
- The replacement field is added.
- The old field is marked as
deprecatedin the API description. - Both fields continue to be returned.
- The old field is only removed with the next major version — never within the current one.
If both fields are sent in a request, the new one takes precedence.
What happens to already-imported documents
Nothing. A document that was imported into the document management system via v1 remains fully valid — it is an ordinary document management object and is not tied to the version through which it was uploaded. An application on v2 reads documents imported via v1 without any special handling.
The connector has its own update cycle
The connector runs on the law firm's server and is updated according to the firm's own schedule. This is an intentional decoupling — a new API version does not force the law firm to update immediately, and an update at the law firm doesn't force the partner to do anything.
What this means for a partner application:
-
It can query the current status.
GET /v1/platform/connector/heartbeatreports whether the law firm's connector is connected, which version it is running, and which capabilities it has registered. This can be used to adapt your own interface — for example, to display a notice while the connector is unreachable. - A connector that is too old will be rejected by the cloud. STP can set a minimum version and block specific versions — for example, if a particular version contains a critical bug. A call to a blocked or outdated installation will fail with a clear explanation rather than breaking silently mid-request. The heartbeat also reports this condition, so the cause can be identified before the first functional call fails.
The capability list is informational, not a gate. The cloud does not reject a call simply because a capability is missing from the list; the check at the cloud level is based on version. If a feature is genuinely missing from the connector, the connector will report that when the call is executed.
The API description
The authoritative technical reference is the OpenAPI description for each major version. It is the definitive source for field names, data types, and required fields; this documentation explains the context but does not replace it.
The current version is available through the STP Download Portal — the same place as the installation packages. It can be used as input for a code generator, making it the fastest way to get a typed client up and running.