Considérations techniques

L’API Keyclic est une API REST. Toutes les opérations sont effectuées via le protocole https et sécurisées par JSON Web Tokens. Les données sont échangées exclusivement au format JSON.

Le nom de domaine de l’API Keyclic est :

api.keyclic.com

Applications et clés d’applications

Tout client de l’API doit transmettre dans les headers de chaque requête une clé définissant l’application sur laquelle il travaille.

Si vous développez un client pour travailler sur une application existante de Keyclic, vous devez connaître la clé de cette application. Si au contraire vous développez un client pour une nouvelle application, merci de vous adresser à la société Keyclic pour que celle-ci crée l’application et sa configuration et vous fournisse la clé correspondante.

Exemples de clés d’applications :

  • com.keyclic.app
  • com.keyclic.city
  • com.keyclic.highway

Chaque requête doit donc préciser, dans ses headers, la valeur du paramètre X-Keyclic-App. Voir ci-dessous le paragraphe Requêtes pour la mise en œuvre.

Notez cependant que la base utilisateurs est commune à toutes les applications Keyclic. De fait, les endpoints d’inscription et de connexion (voir : Authentification et connexion) font exception à la règle ci-dessus : ces deux endpoints n’exigent pas qu’une clé d’application leur soit fournie.

Requêtes

Dans cette documentation, chaque endpoint de l’API sera décrit par le chemin d’accès à la ressource précédé du verbe HTTP.

Exemple :

GET /feedbacks

Le endpoint ci-dessus retourne toutes les demandes. Son URL véritable est

https://api.keyclic.com/feedbacks

mais pour des raisons de concision, dans cette documentation, nous ne préciserons jamais le protocole ni le nom de domaine.

Paramètres d’URL

Dans cette documentation, les variables d’URI (exemples : identifiant d’une ressource, numéro de page, etc) seront exprimés entre accolades. Par exemple, pour récupérer une demande (feedback) donnée :

GET /feedbacks/{feedback}

Dans l’API Keyclic, conformément aux principes d’architecture REST, les paramètres de filtrage sont toujours passés en « query string ». Exemple :

GET /feedbacks?page={page}

Par ailleurs, pour une meilleure lisibilité, les paramètres d’URI seront écrits tels quels dans cette documentation, et non sous leur forme URL encodée :

GET /feedbacks?before=2018-04-22T01:00:00+05:00

Headers

En plus des headers conventionnels de HTTP/1.1, l’API Keyclic accepte, et même exige dans la plupart des cas, le header X-Keyclic-App, correspondant à l’application utilisée (voir ci-dessus : Applications et clés d’applications). Par exemple, pour récupérer toutes les demandes sur l’application com.keyclic.app, la requête comportera le header :

X-Keyclic-App : com.keyclic.app

Tous les endpoints exigent que ce header soit fourni, à l’exception des endpoints de login et de changement de mot de passe. (voir : Authentification et connexion)

Toutes les requêtes (à l’exception du login, du register et du changement de mot de passe) doivent aussi comporter le header Authorization afin d’authentifier l’utilisateur. (voir : Authentification et connexion)

Format des requêtes et réponses

Le seul type de contenu accepté par l’API Keyclic est JSON. Vos requêtes devront donc comporter le header :

Content-type: application/json

et le corps des requêtes devra toujours être formaté en JSON. Les réponses sont également toujours retournées au format JSON.

Envoi de fichiers

Tous les fichiers sont envoyés en base 64 à l’API. Voici par exemple l’ajout d’une image représentant un carré rouge d’1 pixel sur 1 sur une demande :

POST /feedbacks/{feedback}/images

{
    "image":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAIAAAACDbGyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QIVDRUfvq7u+AAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAUSURBVAjXY3wrIcGABJgYUAGpfABZiwEnbOeFrwAAAABJRU5ErkJggg=="
}

Modification de ressources

Dans l’API Keyclic, la modification des ressources s’effectue avec la méthode PATCH. Contrairement à la méthode PUT, la méthode PATCH permet de modifier une seule propriété ou une partie seulement des propriétés d’une ressource, sans qu’il soit nécessaire d’en envoyer une représentation complète. Le format utilisé pour la description du patch est JSON Patch.

À titre d’exemple, voici la modification de la propriété billingEmailAddress d’une organisation :

PATCH /organizations/{organization}

{
    "billingEmailAddress":"test@test.com"
}

Retours d’erreurs

Toute erreur entraîne une réponse de code 4xx reflétant le type d’erreur.

Quand il s’agit d’une erreur de type 400 (Bad Request), les raisons de l’erreur sont retournées.

Les erreurs sont décrites au format vdn.error.

L’exemple suivant montre un retour d’erreur de validation. Le champ path indique la propriété sur laquelle porte l’erreur (ici : reporter), et le champ message indique la nature de l’erreur.

{
    "@context": "https://github.com/blongden/vnd.error",
    "@type": "ValidationError",
    "message": "Validation failed.",
    "total": 1,
    "_embedded": {
        "errors": [
            {
                "@context": "https://github.com/blongden/vnd.error",
                "@type": "Error",
                "message": "Cette valeur ne doit pas \u00eatre vide.",
                "path": "reporter"
            }
        ]
    }
}

Changements de statut

Plusieurs ressources manipulées par l’API ont un cycle de vie et possèdent un certain statut à un instant donné. C’est le cas des demandes et des interventions.

Pour ces ressources, l’état est toujours indiqué dans la réponse avec le paramètre state, et les actions possibles pour faire évoluer ce statut sont toujours indiquées sous le paramètre stateTransitions. Exemple :

GET reports/{report}

Réponse (partielle) :

{
    "type": "Report",
    "id": "cb7118b5-a821-4cf2-9475-0c0d0efdb8d0",
    "state": "NEW",
    "_embedded": {
        "stateTransitions": [
            "accept",
            "refuse"
        ]
    }
}

Dans l’exemple ci-dessus, la demande est en statut NEW et les actions possibles sur son statut sont accept et refuse.

Tout changement de statut est effectué avec la méthode POST en passant le nom de la transition dans le body.

Par exemple, pour accepter la demande ci-dessus :

POST /reports/{report}/workflow/transition

{
    "transition": "accept"
}

La réponse nous informe que la demande possède désormais le statut ACCEPTED, et que les actions possibles sont désormais refuse, hold et progress :

{
    "type": "Report",
    "id": "32219286-528a-4f97-b81e-fe7a8cb85707",
    "state": "ACCEPTED",
    "_embedded": {
        "stateTransitions": [
            "refuse",
            "hold",
            "progress"
        ]
    }
}

Les actions et status possibles pour chaque type de ressources sont décrits dans les sections idoines de cette documentation.