Technical considerations

The Keyclic API is RESTful. Every operation is sent through HTTPS and is secured with JSON Web Tokens. The data is sent only in JSON format.

The Keyclic API’s domain name is :

api.keyclic.com

Applications and Application’s key

Every client of the API must send a key identifying his application in the request header

If you are developing a client to work with an existing Keyclic application, you have to know the application’s key. Else if you wish to develop a client for a new application, please contact Keyclic. They will create the new application, configure it and send you the corresponding key.

Examples of an application’s key :

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

Then every request header has to contain a X-Keyclic-App field with a value like the examples above. Refer to this paragraph Requests for the “implementation”.

However, users accounts are shared to all Keyclic applications. Therefore, login and register endpoints do not require to provide an application key (cf : Authentication and connection).

Requests

In this documentation, each API’s endpoint will be described by an HTTP verb and the path to access the resource.

Example :

GET /feedbacks

This endpoint returns every feedback. Its actual URL is

https://api.keyclic.com/feedbacks

but to avoid redundancy, in the following examples, we will show neither the protocol nor the domain name.

URL’s parameters

In this documentation, URIs variables, such as a resource identifier, a page number, etc, will be between curly brackets. For example, to retrieve a single feedback :

GET /feedbacks/{feedback}

In the Keyclic API, in accordance with REST principles, the filtering parameters will always be in the query string. Example :

GET /feedbacks?page={page}

Moreover, for a better visibility, URI’s parameters will be written as such and not in their encoded URL form :

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

Headers

Besides conventional HTTP/1.1 headers, Keyclic API accepts and in most cases requires, the header X-Keyclic-App, corresponding to the application used (see above : Applications and Application’s key). For example, to get all feedbacks from the com.keyclic.app application, the request will have to contain the following header :

X-Keyclic-App : com.keyclic.app

Every endpoint requires this header, except for login and password modification. (refer : Authentication and connection)

Also, every request (except login, register and password modification) must contain the Authorization header (see : Authentication and connection).

Request and response format

The only type of content accepted by the Keyclic API is JSON. Requests must contain the header :

Content-type: application/json

and the body will always have to in JSON format. The responses are returned to the JSON format too.

Send files

Files are sent in base 64 to the API. Here is an example of adding an image to a feedback :

POST /feedbacks/{feedback}/images

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

Resource modification

In the Keyclic API, resource modification is made with the PATCH method. Unlike the PUT method, PATCH allows to modify a single or some properties of a resource without sending every property of the modified resource.

Here is an example to change the property billingEmailAddress of an organization :

PATCH /organizations/{organization}

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

Errors

Every error send a code 4xx representing the type of error.

When an code 400 (Bad Request) is returned, the reasons are sent.

Errors follow the format vdn.error.

The following example displays a validation error.

{
   "@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"
         }
      ]
   }
}

The field path indicates which property triggered the error (here: reporter), and the field message explains the error.

State change

Several resources of the API possess a life cycle and a state for a given moment. Those resources are feedbacks, reports and operations.

For these resources, the state is always indicated in the response with the field state, and the next possible actions to change this state are displayed in the parameter stateTransitions. Example :

GET reports/{report}

Response (partial) :

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

In the example above, the report has a state NEW and the possible actions on its state are accept and refuse.

Actions on the state of a resource is made through the POST method, with the path and the new value.

For example, to accept a report :

POST /reports/{report}/workflow/transition

{
                "transition": "accept"
}

This request will send the following response :

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

The report’s state is now ACCEPTED, and the next actions are refuse, hold and progress.

Actions and states for each kind of resource are described in the appropriate sections of the documentation.