API design
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.
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.
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. |
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.Some endpoints represent resources that can contain a lot 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, that can be set using the
limit
query parameter. Since pagination is mandatory, an implicit limit
is used if not explicitly provided. Also, limit
has a maximum value of 500.Most of collection endpoints accept an
offset
parameters. Combine it with limit
to access arbitrary ranges of items.Paginated resources also return an easy-to-use
_link
property with links to use for sibling loads.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.
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="
}
}
}
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.
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. |
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.
Last modified 1mo ago