API design

Root and versioning

Current version (2.0) of our API is available, for each API domain, at the following path:

https://{domain}.biapi.pro/2.0/*

In this documentation, all path references and examples are relative to this root.

Services design

Our API exposes a set of endpoints to interact with resources. Endpoint routes are named after the resources they interact with:

Path example	Resource
/connections/*	Manage connections
/accounts/*	Manage bank accounts
/auth/*	Common prefix for authentication services

Deep paths are sometimes uses to access sub-resources:

/users/1/connections/2/accounts/23/transactions/48

Interactions with resources mostly follow conventions by using dedicated HTTP methods to perform operations:

Method	Operation
GET /resources	List resources
GET /resources/{id}	Get a unique resource by id
POST /resources	Create a new resource
POST /resources/{id} or PUT /resources/{id}	Update a resource
DELETE /resources/{id}	Delete a resource

Not all operations are valid for every resource, API reference of each service describes the specific behaviors by endpoint.

HTTP response codes

We use various relevant HTTP response codes depending on the success or failure of the request. Successful responses (2XX status) return the entity documented with each endpoint in the services reference. Error responses (4XX and 5XX status) use a common error format.

Code	Message	Description
200	OK	Defaut success code for responses.
202	Accepted	Alternate success code for requests that need further interaction to resume the operation (e.g. connection addition or sync).
204	No content	Success code for requests that return nothing.
400	Bad request	Error code when the request is invalid, e.g. the supplied parameters are incorrect.
401	Unauthorized	Error code when the service requires authentication and the proper header was incorrectly provided.
403	Forbidden	Error code when an authentication token with insufficient scope was provided to access an endpoint.
404	Not found	Error code when the route was incorrect, or the resource is unknown for the provided authorization scope.
409	Conflict	Error code when a request could not be honored because of a conflicting state with the API.
500	Internal servor error	Error code for failures related to internal bugs.
503	Service unavailable	Error code when our API is temporarily down for maintenance.

Error handling should be preferably based on the error code rather than the HTTP status code.

Requests and responses format

Requests to the API, unless specified, should be formatted in JSON, with the appropriate content-type request header.

For convenience, we also accept x-www-form-urlencoded requests when the body does not imply nested levels.

Responses are exclusively returned as JSON objects, you can specify it using the recommended accept request header.

Lists pagination

On endpoints that allow access to a list of items, pagination is used to easily slice the results and navigate the whole collection.

Pagination relies on a limit on the number of returned items in a single API call, that can be set using the limit query parameter. Usage of the limit parameter is advised for most resources, and mandatory for some (explicitly documented), in order to control the maximum number of returned items.

Except documented otherwise, limit has a maximum value of 1000.

Basic offset pagination

Most of collection endpoints accept an offset parameters. Combine it with limit to access arbitrary ranges of items.

Relational pagination

Some paginated resources also return an easy-to-use _link property with links to use for sibling loads.

PaginationLinks object

Property	Type	Description
self	Link object	Reference to the current page (with a href property).
prev	Link object or null	Reference to the previous page (with a href property), if any.
next	Link object or null	Full address of the next page (with a href property), if any.

Each of these link references is either null (if there is no previous or next page), or is an object with an href property, which is the URL of the relevant page (previous, current or next).

The provided links are opaque and should be used "as is", they encapsulate the filtering logic expressed by parameters on the initial request.

Example

GET /users/me/transactions?min_date=2022-12-01&income=false&limit=50

{
  "transactions": [ ... ],
  "_links": {
    "prev": null,
    "self": {
      "href": "https://{domain}.biapi.pro/2.0/users/me/transactions?min_date=2022-12-01&income=false&limit=50"
    },
    "next": {
      "href": "https://{domain}.biapi.pro/2.0/users/me/transactions?min_date=2022-12-01&income=false&limit=50&cursor=W3sib3AiOiAibHQiLCAidmFsdWUiOiAiMjAyMC0wMy0wOCJ9LCB7Im9wIjogImd0IiwgInZhbHVlIjogOTgwNzg3fV0="
    }
  }
}

Lists temporal filtering

Some resources may be filtered using a temporal criterion on a property. In this case, the list endpoint usually support min_date and max_date parameters.

The value can be a date (in ISO YYYY-MM-DD format), but also a month or a year.

Lists implicit filtering

Some collections use soft-deletion or an enabled/disabled state. For these resources, implicit filtering is applied to exclude deleted or disabled resources from the default API responses. You can access the excluded items by adding the all flag query parameter.

Example:

Path	Resources
/user/me/accounts	Return bank accounts that are not disabled.
/user/me/accounts?all	Return all bank accounts.
/user/me/accounts/123?all	Interact with the disabled account 123.

Response expansion

Most API calls support an expansion mechanism to enrich the response with linked sub-resources. This enables fetching a full set of data without performing multiple requests. Expansion is defined using the expand query parameter with a comma-separated list of wanted sub-resources. Nested sub-resources are also available with brackets.

Example: The following request will return the bank account 123 with associated connection, the list of latest transactions (it is not possible to control pagination or filtering here), and for each transaction the associated category:

GET /users/me/connections/123?expand=accounts,connector[countries]

{
  "id" : 123,
  "state": null,
  "accounts": [
    { "id": 1234, "name": "Current account", "disabled": "2020-06-01 12:34:56", … },
    { "id": 4567, "name": "Saving account", "disabled": "2020-06-01 12:34:56", … },
    …
  ],
  "connector" : {
    "id": 40,
    "name": "Connecteur de test",
    "auth_mechanism": "credentials",
    "capabilities": [ "bank", "document", "profile", … ],
    "countries": [ { "id": "fr", "name": "France" }, … ]
  },
  …
}

Each resource defines in its documentation the available expansions.