Straliens Server REST API

Avant de commencer

Remarques

• Tous les endpoints sont préfixés par /api. Ainsi, quand il est noté /users/:id, il faut lire /api/users/:id.
• Le format attendu dans les payloads pour les requêtes POST, PUT, etc, est le classique x-www-form-urlencoded.

Sections

Les sections sont des paramètres que vous pourrez ajouter à une URL pour développer le contenu de la réponse.

Par exemple, un utilisateur possède un champ teamId. Le corps de l'équipe en elle-même n'est pas incluse dans la réponse par défaut. Pour obtenir en même temps les données de l'utilisateur et celles de l'équipe, il faudra former une URL comme celle-ci : GET /users/42?sections=team,other_section. Un champ team apparaîtra alors, imbriquant l'équipe dans l'utilisateur.

Notez que les sections peuvent être également demandés sur des requêtes autres que GET. Par exemple, il est tout à fait possible d'utiliser ?sections=team sur un user en POST, pour obtenir immédiatement les informations sur l'équipe.

Erreurs

Les erreurs sont toujours formatées selon un format fixe et prévisible. Le statut HTTP est défini au mieux, les requêtes fructueuses étant dans la plage 2xx et les erreurs étant dans la plage 4xx.

Pour plus de détails concernant l'erreur, la payload embarque un objet JSON avec les propriétés suivantes :

• success positionné à false
• status : un rappel du code d'erreur HTTP
• type : type de l'erreur, par ex. NotFoundError ou ValidationError.
• message : le message principal attaché à l'erreur, en langage humain (phrase en anglais)
• Des champs optionnels qui peuvent être ajoutés par le service renvoyant l'erreur. Par exemple, une ValidationError pour la validation d'un formulaire contiendra aussi un champ fields contenant une liste des champs qui n'ont pas passé la validation.

Exemple :

{
  "success": false,
  "status": 400,
  "type": "ValidationError",
  "message": "The form has erroneous fields!",
  "fields": [
    {
      "path": "nickname",
      "message": "nickname cannot be null"
    }
  ]
}

Endpoints

Services

POST /services/#

Payload :

• nickname : nickname de l'utilisateur, ou au choix, son email
• password : mot de passe

Réponse :

{
  "success": true,
  "message": "User authenticated"
}

Users

Sections :

• team : l'équipe dont l'utilisateur fait part.

GET /users

Retourne la liste de tous les utilisateurs, sans pagination.

Réponse :

Format : tableau simple d'utilisateurs, formatés comme en GET.

POST /users

Crée un utilisateur.

Payload :

• nickname : entre 3 et 25 caractères
• email : entre 3 et 25 caractères
• password : en clair
• teamId : optionnel, ID de l'équipe

Réponse :

• Header Location contenant l'URL de lecture de la ressource.

Format : utilisateur formaté comme en GET.

GET /users/:id

Récupère un seul utilisateur, par ID.

Réponse:

{  
   "id": 25,
   "nickname": "Test",
   "createdAt": "2015-06-14T14:08:56.000Z",
   "updatedAt": "2015-06-14T14:08:56.000Z",
   "teamId": 1
}