Skip to content

Compatibility and Deprecation

When an API module is publicly released, the request and response model are guaranteed to stay consistent and backwards compatible. Breaking changes will not be done in a released version, instead we will release a new version of the module, which may have a different structure and contract.

However, the following changes are not considered breaking, and any integrating client should make sure to allow for such changes:

  • New endpoints - New endpoints may be added at any time.
  • New output fields - Adding a new output field may be done at any time.
  • New enum values - A field with defined valid output values (enum field) may be extended with new enum values. Integrating clients should therefore handle new/unknown enum values.
  • New input fields - New input fields, and new enum values for input enum fields, may be added. However, such fields are not added as mandatory/required input fields, as that would constitute a breaking API change.
  • New or changed list entries - For an endpoint returning a list of values, e.g. case categories or alarm categories, it is not considered a breaking change to add new entries to the list, or remove entries from the list. These are considered dynamic values.

Deprecations and removal of APIs

Deprecation of single fields

Single fields may be marked as deprecated in both input and output. Deprecated fields will NOT be removed for the lifetime of the endpoint, to avoid compability issues.

For input fields, a deprecated field may be ignored if it no longer has any relevance for the endpoint; without causing breaking behaviour. For output fields, a deprecated field value may be omitted (value null), if we no longer have sensible values to return for it.

Tip

For a response field marked as "non-null", returning null is a breach of contract. However, clients should always code defensively around response values, as even fields/objects marked as non-null in the API may be null if the system fails to resolve them properly, returning a best-effort response instead of failing completely.

The OpenAPI documentation will point to how the field should be replaced.

Deprecation of endpoints

When an API endpoint is deprecated, the OpenAPI documentation will mark it as documented, and the endpoint description will point you to which endpoint to use instead.

In addition, we will list deprecated endpoints in the deprecation overview. The endpoint itself will start emitting a WARNING message:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
  "messages": [
        {
            "field": null,
            "message": "This endpoint has been deprecated, and will be disabled after 2026-09-01T00:00:00Z. Please check https://docs.mnemonic.no/general_integration_guide/01-compatibility_deprecation.html for information about how to migrate.",
            "messageTemplate": "endpoint.deprecated",
            "parameter": null,
            "timestamp": 1786960764280,
            "type": "WARNING"
        }
    ],

In addition, it will emit the header Argus-Deprecated-Deadline with the deprecation deadline, e.g. Argus-Deprecated-Deadline: 2026-09-01T00:00:00Z

Disabling of deprecated endpoints

Deprecated endpoints will have a grace period defined on the endpoint, after which the endpoint will be automatically disabled.

Disabled endpoints will fail with HTTP error 410 GONE:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "count": 0,
    "data": null,
    "limit": 0,
    "messages": [
        {
            "field": null,
            "message": "This endpoint has been disabled for removal. You can override this with a Argus-Override-Disabled-Endpoints header. See https://docs.mnemonic.no/general_integration_guide/01-compatibility_deprecation.html for details.",
            "messageTemplate": "endpoint.disabled",
            "parameter": null,
            "timestamp": 1786960917999,
            "type": "ACTION_ERROR"
        }
    ],
    "metaData": {},
    "offset": 0,
    "responseCode": 410,
    "size": 0
}

For integrations that suddenly start to fail due to endpoints being disabled, we provide a short emergency migration grace period, before the endpoint is permanently removed.

As mentioned in the returned error message, clients may set HTTP request header Argus-Override-Disabled-Endpoints: true in the request to override the disabling of the endpoint. This will let the client continue to use the deprecated endpoint until the removal-deadline is hit.

Using the endpoint with this option will always emit a warning message in the response: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 "messages": [
        {
            "field": null,
            "message": "You are using a disabled endpoint. The endpoint will be permanently removed after 2026-09-01T00:00:00Z",
            "messageTemplate": "deprecated.endpoint",
            "parameter": null,
            "timestamp": 1786961313439,
            "type": "INFO"
        }
    ]

Once the removal deadline is hit, the endpoint is completely dead.

Warning

If you update your client to use the Argus-Override-Disabled-Endpoints: true header, make sure you immediately schedule migration to new endpoints well in advance of the removal date!