API Versioning
Semantic Versioning
APIs are versioned using Semantic Versioning : Given a version number MAJOR.MINOR.PATCH, increment the:- MAJOR version when Datanumia makes incompatible API changes
- MINOR version when Datanumia adds functionality in a backward compatible manner
- PATCH version when Datanumia makes backward compatible bug fixes.
Backward compatibility
Most changes to Datanumia APIs are made in a backward compatible manner. Examples of backward compatible updates from version X.Y to version X.Y+1:- Datanumia can add optional attributes in the API request
- Datanumia can add attributes in the API response
- Datanumia can remove an optional attribute in the API response
- accept a new attribute or object in the API response
- Datanumia will not remove a mandatory attribute in the API response
- Datanumia will not remove a resource or a method of an API
- Datanumia will not change an attribute type in the API response
Versioning policy
When an API is deprecated :- advanced noticed is given 6 months before support ends
- the documentation is tagged as “deprecated”
- the documentation states the date of the end of life
- you will be contacted by email by your Customer Success Manager
- It do not respond anymore. Trying to use this API version will fail and return 403 Access Denied.
- Old API versions are tracked in the futur Release Notes section. Coming soon
Unit and Bulk APIs
When to use Unit APIs
The unit APIs must be used when request are made on a single object as described in core conceptsWhen to use Bulk APIs
The bulk APIs must be used when requests are asynchronous and made in bulk (or batch). The bulk APIs are optimized for working with large sets of data. You can use it to manage many operations.File formats, size and encoding
The bulk API uses JSON files compressed in .tar.gz archives. JSON files are not processed directly by Datanumia, only archives are processed. Each API call contains one .tar.gz file. The data schema is compliant with JSON schema and consistent with data schema described with OpenAPI. Encoding is : UTF-8 To optimize performance :- the maximum size of the archive file is limited to 5 Mo.
- the maximum number of JSON files in an archive is limited to 10.
Processing order
HTTP API calls are processed on a first come first served basis. For the bulk API, no order is guaranteed for the files within an archive and for the operations within a file.Error management
Home API will return valid HTTP response codes based on the success of your request. The following table can be used as a reference for the returned response codes.
For 400 HTTP status code which are functional errors, the Home API may return more detailed error through the errorCode attribute in the JSON error response. The response will also contain an errorMessage attribute containing a more friendly error string.