NORME & GUIDE D'UTILISATION

FRANCE UK SPAIN GERMANY PORTUGAL
Voici quelques éléments visant à faciliter l'utilisation de la plateforme.
Les informations qui suivent s'appliquent à toutes les APIs décrites dans la documentation technique.

URLs

Les APIs Altima s'appuient sur un design REST : orienté "ressources".
Les urls sont donc normalisées et s'appuient sur les "verbes" HTTP standards : GET/POST/PATCH/DELETE/etc...

Environnements :

La plateforme ALTIMA dispose de deux environnements distincts, un de Test vous permettant d'intégrer et de tester nos APIs avec un nombre d'appels journaliers limité et un de Production.
Les URL ci-dessous permettent d'identifier les différents environnements :

Notations :

Dans la documentation technique les environnements sont notés de la manière suivante :
https://(test|www).api.altima-assurances/* le caractère de séparation | siginifiant OU

Obtenir une liste de ressources :

GET https://< xxx.api.altima-assurances.fr >/v1/ressources

Exemple de réponse : HTTP 200 - OK
  [{
      "id":1,
      "code":"code1"
  }, {
      "id":2,
      "code":"code2"
  }, {
      "id":3,
      "code":"code3"
  }]

Obtenir une ressource :

GET https://< xxx.api.altima-assurances.fr >/v1/ressources/:id

Exemple de réponse : HTTP 200 - OK
  {
      "id":1,
      "code":"code1"
  }

Rechercher une (ou plusieurs) ressource(s) :

GET https://< xxx.api.altima-assurances.fr >/v1/ressources?param1=aaaa&param2=bbbb

Exemple de réponse : HTTP 200 - OK
  [{
      "id":1,
      "code":"code1"
  }, {
      "id":3,
      "code":"code3"
  }]

Créer une ressource :

POST https://< xxx.api.altima-assurances.fr >/v1/ressources

Exemple de réponse : HTTP 201 - CREATED
Headers : Location : https://< xxx.api.altima-assurances.fr >/v1/ressources/1

Mettre à jour une ressource :

PATCH https://< xxx.api.altima-assurances.fr >/v1/ressources

Exemple de réponse : HTTP 200 - OK

Supprimer une ressource :

DELETE https://< xxx.api.altima-assurances.fr >/v1/ressources/:id

Exemple de réponse : HTTP 204 - No Content

Format d'échange

Le format d'échange adopté au travers des appels HTTP est exclusivement le JSON (content-type : application/json), à l'exception des échanges de documents (upload/download).
Ce format s'applique à la représentation des ressources (Corps de la réponse pour du GET, Corps de la requête pour du POST/PATCH).
Ce format s'applique également à la représentation des erreurs. Leur contenu peut varier selon la nature de l'erreur.

Exemple : HTTP 500 - Internal Server Error

  {
  "error" : "Internal Server Error",
  "error_description" : "An error occured during..."
  }

Exemple : HTTP 422 - Unprocessable Entity

  {
  "error" : "Unprocessable Entity",
  "error_description" : "Paramètre(s) d'entrée non valides",
  "error_details" : [
      "Le champ xxx est obligatoire",
      "Le format du champ yyy est invalide",
      ...
  ]
  }

Exemple : HTTP 404 - Not Found

  {
  "error" : "Not Found",
  "error_description" : "Le document xxx n'existe pas."
  }

Versionning

Le versionning de nos APIs est explicitement présent dans leurs urls.
En cas d'évolution majeure et non "rétro-compatible", une nouvelle version est rendue disponible. La précédente version reste accessible en mode "déprécié", sur une durée limitée.
En cas d'évolution mineure et rétro-compatible, l'url ainsi que les entrées/sorties restent inchangées.
Nous vous conseillons d'opérer les changements nécessaires au plus tôt afin de pouvoir bénéficier des nouvelles améliorations/fonctionnalités, mais aussi d'éviter toute rupture de service lors de l'abandon des APIs dépréciées.
Veuillez consulter la documentation technique afin d'obtenir les détails permettant d'anticiper ces changements.

Sécurité

Dans le cadre de notre partenariat, nous vous avons fournit des clés d'API qui vous permet d'accéder aux différents environnements de cette plateforme. Cette clé est requise par toutes les APIs afin de franchir les contrôles de sécurité associés.

Implémentation :

Erreurs :

Si l'un ou l'autre de ces headers est absent ou invalide, la plateforme renverra une erreur HTTP 401 : Unauthorized accompagnée d'un message en expliquant les raisons.

Exemple :
  {
  "error" : "Unauthorized",
  "error_description" : "You're not authorized to access this api, Header X-Auth-App-Id or X-Auth-Key is missing"
  }