Authentication

Every endpoint is secured using with an access token of type Bearer. All endpoints are accessible only through MTLS protocol.

Get new Access Token

The basic authorization header should be constructed using Authorization: Basic <credentials>, where credentials is the Base64 encoding of ID and secret joined by a single colon :

For example, if we use Aladdin as the ID and open sesame as the secret, then the field's value is the Base64 encoding of Aladdin:open sesame, or QWxhZGRpbjpvcGVuIHNlc2FtZQ==. Then the Authorization header field will appear as:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

curl --location 'https://foundation.clv.cardif.api.staging.bnpparibas/oauth2/v1/token' \
  -E <certificate> \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic base64(client_id:clientsecret)' \
  --data-urlencode 'grant_type=client_credentials'

You will get a response according to oauth2 specs. Access Token can be used as a bearer for api calls.

{
  //...
  "token_type": "Bearer",
  "issued_at": 1678183638441,
  "access_token": "<bearer>"
  //...
}

Content negotiation

Encoding

gzip is supported for mime types text/html, text/xml, text/plain, text/css, text/javascript, application/javascript, application/json, application/xml if the response size exceed 2KB.

curl -v --location '<server>/policies' \
  --header 'Accept-Encoding: gzip, deflate, br' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <bearer>'

> GET /policies HTTP/1.1
> User-Agent: curl/7.80.0
> Accept-Encoding: gzip, deflate, br
> Accept: application/json
> ...

< HTTP/1.1 200
...
< Content-Encoding: gzip
< Content-Type: application/json

Content Type

The api will answer to the requested content type. Supported Media types are application/json, application/xml, application/cbor and application/x-jackson-smile

curl --location '<server>/policies' \
  --header 'Accept: application/xml' \
  --header 'Authorization: Bearer <bearer>'


<PagedModel>
    ...
</PagedModel>

Language

Currency and financial amount will always have the raw value alongside the formatted one. The format will be deducted from the given locale in Accept-Language header

curl --location '<server>/policies/<id>/valuations' \
  --header 'Accept-Language: en-US' \
  --header 'Authorization: Bearer <bearer>'

{
  "amount": 6258960.926773,
  "currency": "EUR",
  "formatted": "EUR6,258,960.93"
}

curl --location '<server>/policies/<id>/valuations' \
  --header 'Accept-Language: fr-FR' \
  --header 'Authorization: Bearer <bearer>'

{
  "amount": 6258960.926773,
  "currency": "EUR",
  "formatted": "6 258 960,93 EUR"
}

Search

Most search endpoint can be filtered and sorted

Pagination

If the search has pagination capabilities, the resource takes the following query parameters:

page: The page number to access (0 indexed, defaults to 0).
size: The page size requested (defaults to 20, unless another specific defaults applies).
sort: A collection of sort directives in the format property,[asc|desc]. If not specified, it takes in ascendant format. Ex: sort=someStatus&sort=someDate,desc will first order on someStatus in ascending, then on someDate in descending.

Filtering

If the search has filtering capabilities, the resource takes the following query parameters property.operation=value

The operations are

equal: a=b strict equality policyId.equal=0123456 and shorthand policyId=0123456 (alias eq or equals)
oneOf: a=b or a=c multiple choice policyId.oneOf=0123456&policyId.oneOf=987654 (alias in)
lessThan: a< b effectiveDate.lowerThan=2020-01-01 (alias lt or below)
lessThanOrEqual: a<=b effectiveDate.lowerThanOrEqual=2020-01-01 (alias lte or most or loe)
greaterThan: a>b effectiveDate.greaterThan=2020-01-01 (alias gt or above)
greaterThanOrEqual: a>=b effectiveDate.greaterThanOrEqual=2020-01-01 (alias gte or least or goe)
include: 'worl' is included in 'hello world' policyId.include=123 (alias includes or contain or contains)

Please note that depending on the actual type of property, some operator might not be available. For example, it does not make sense to have "greaterThanOrEqual" operation on String ids.

Hateoas + HAL

The HAL format is strictly coupled to HATEOAS. The main target of HATEOAS is to decouple the API Consumer from the paths used in the API. The API Client uses the links generated by our API instead of building them from the documentation. This is less error-prone for the API Consumer and it can allow making changes in the API without affecting the API Consumer code.

Pagination links with embedded resources

{
  "_embedded": {
    "policies": [
      // Array of policies
    ]
  },
  "_links": {
    "first": {
      "href": "<url>/policies?page=0&size=10"
    },
    "self": {
      "href": "<url>/policies?page=0&size=10"
    },
    "next": {
      "href": "<url>/policies?page=1&size=10"
    },
    "last": {
      "href": "<url>/policies?page=8892&size=10"
    }
  },
  "page": {
    "size": 10,
    "totalElements": 88925,
    "totalPages": 8893,
    "number": 0
  }
}

Resources links

{
  "policyId": "<id>",
  // ... properties
  "_links": {
    "self": {
      "href": "<url>/policies/<id>"
    },
    "actors": {
      "href": "<url>/policies/<id>/actors"
    },
    "holders": {
      "href": "<url>/policies/<id>/actors?roleType.oneOf=HOLDER"
    },
    "insured": {
      "href": "<url>/policies/<id>/actors?roleType.oneOf=ASSURED"
    },
    "valuations": {
      "href": "<url>/policies/<id>/valuations"
    },
    "yearToYearValuations": {
      "href": "<url>/policies/<id>/valuations?size=13&page=0&sort=date,desc"
    },
    "lastValuation": {
      "href": "<url>/policies/<id>/valuations?size=1&page=0&sort=date,desc"
    }
  }
}

Policy Management System