Standards

API standards define the structure of:

• requests
• responses
• status codes
• errors
• general API behaviour

Non-breaking and breaking changes

At the moment, we do not introduce any updates to our APIs that cause breaking changes.

Non-breaking changes

We consider the following changes to be non-breaking:

• Adding a new endpoint
• Adding a new field to a request body
• Adding a new field to a response body
• Changing a field in a request body from required to optional, without a behavioural change
• Changing a field in a response body from optional to required
• Adding a request or response header entry
• Changing a request header entry from required to optional
• Changing a response header entry from optional to required
• Changing the value of a header
• Changing a response error message
• Adding a new response status code

Breaking changes

We consider the following changes to be breaking:

• Adding a required field to a request body
• Renaming a field in a request body
• Removing a field from a request body
• Removing a field from a response body
• Changing a field in a response body from required to optional
• Removing a request header
• Removing a required response header
• Adding a required request header
• Changing a response header from required to optional
• Changing the type of a field in a request or response body
• Changing the behaviour of the API in a way that requires you to change your integration

Message formats

Requests are sent as JSON or, in some cases, form-encoded. String properties are encoded using UTF-8, and date properties are represented by UNIX Epoch time in milliseconds or, in some cases, ISO 8601 strings.

HTTPS and TLS

The Adfin API will only serve traffic over HTTPS, and will include an HSTS response header in order to let browsers and other client software enforce this. TLS v1.2 or higher is required by the Adfin API.

Server certificate

The Adfin API server certificate should be trusted by all up-to-date root certificate trust stores provided by operating systems and browsers. If your software uses a custom certificate trust store, also known as certificate pinning, you will have to trust the current and upcoming root certificates of the Certificate Authority (CA) used by the Adfin API.

Ensure that your application trusts the following DigiCert root certificates:

• DigiCert Global Root CA
• DigiCert Global Root G2
• DigiCert TLS ECC P384 Root G5
• DigiCert TLS RSA4096 Root G5
• DigiCert ECC P384 Root G5
• DigiCert RSA4096 Root G5

Adfins certificates will be issued by an intermediate CA of any of the above DigiCert root CAs, and DigiCert replaces their intermediate CA certificates on a regular basis. Adfin may also renew its DigiCert server certificates unannounced. To avoid unexpected connectivity issues, Adfin recommends to only trust DigiCert's root certificates and avoid depending on any fixed part of the server certificate chain other than the root certificates.

Rate limits

To ensure service stability, the Adfin API validates request rate limits on a per app ID basis.

If you make an excessive amount of requests, you will receive an HTTP 429 Too Many Requests response code. If this occurs during expected use of the Adfin API, please contact Adfin support to resolve the issue.

Idempotency and caching

Idempotency means that making multiple identical requests has the same effect as making a single request. Idempotency can be used to safely retry requests without accidentally performing the same operation twice.

Include the following header to perform an idempotent request:Idempotency-Key: b5ed239e-3c72-433d-afe1-cfb137d76b2b

Any header value can be used to perform an idempotent request. We recommend using a high entropy string when doing so, for example, UUID v4.

Results are saved only if an API endpoint started to execute. Idempotent results aren't saved if incoming parameters fail validation or if a request conflicts with another one that executed at the same time. Requests like these can safely be retried.

Keys are removed from the system after 24 hours and can be used again for subsequent requests.

Authentication

Adfin accepts client credentials (client_id and client_secret) as an OAuth client authentication method to fulfill interoperability requirements.

Adfin uses access tokens to authenticate and authorise API requests. The access token is provided through the HTTP Authorization header, such as Authorization: Bearer {access token}, and is valid for a limited time. When an access token has expired, the API call will return the HTTP status code 401 Unauthorized and a new access token has to be acquired.