Comment on page

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

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

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

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.

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.

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.

Next - Overview

Errors

Last modified 13d ago