> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datanumia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

Home API is based on HTTPS, REST API, OpenAPI and OAuth2.

## 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.

The API major version is shown in the API URL.

```
POST /api/v2/sites/1000005_01
```

This versioning is applied to an API, meaning a group of resources and HTTP methods. 

### 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

This means that you must manage some changes on the APIs : 

* accept a new attribute or object in the API response

Examples of what Datanumia will not do :

* 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

When an API is removed :

* 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**. <Badge icon="clock" stroke color="blue" size="lg">Coming soon</Badge>

## 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 concepts](/docs/DatanumiaHome/01-introduction/03-core-concepts)

### When 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.

| HTTP status code | Description |
| - | - |
| `200` (OK) | The request completed successfully |
| `204` (NO CONTENT) | The request completed successfully and returned no content. |
| `400` (BAD REQUEST) | The request was improperly formatted, or a functional error occurred during the processing of the request |
| `401` (UNAUTHORIZED) | The Authorization header was missing or invalid. |
| `403` (FORBIDDEN) | The Authorization token did not have permission to the resource. |
| `404` (NOT FOUND) | The resource at the location specified does not exist. |
| `5xx` (SERVER ERROR) | The server had an error processing your request. |

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.

## Idempotency

Datanumia APIs are idempotent.
Calling multiple times the same operation will lead to the same result.

## Data format

### Timestamp format

Timestamps must be provided with the explicit UTC format (“Z” at the end of the timestamp).