Bee public REST API

Service REST publique dédié aux développeurs externes

Introduction

Trois paquets externes sont abondamment utilisés dans ce projet afin de générer les définitions Swagger de façon simple. Il est donc fortement conseillé de se référencer à leur documentation.

• typescript-rest permet de générer des routes express à l'aide de decorators sur les classes Typescript.
• typescript-ioc permet de gérer l'injection de dépendances avec des decorators (pas le choix à cause de typescript-rest).
• typescript-rest-swagger permet de générer les définitions Swagger correspondant aux classes implémentées.

Documentation

Pour générer le site de documentation, il faut installer les deux projets pip suivants:

sudo pip3 install mkdocs mkdocs-material mkdocs-minify-plugin

Puis exécuter la commande :

npm run build-doc

L'exécution de cette commande embarque également la documentation du SDK

Publication

Pour publier le paquet @ubstream/ubstream-node-client-sdk il faut :

Incrémenter la version du paquet SDK

npm version patch

S'identifier sur le registry NPM:

npm login --scope=@ubstream --registry=https://registry.npmjs.org

Publier le paquet:

npm publish --scope=@ubstream --access=public --registry=https://registry.npmjs.org

Contribution

Toute modification dans l'API publique d'Ubstream devra respecter les règles suivantes :

• Il doit être possible pour les consommateurs de notre API de deviner tant que possible les différentes routes de l'API. Ainsi, les segments de routes doivent tous être déclarés au pluriel de façon à respecter une certaine homogénéité. Le principe REST doit s'appliquer au maximum et les verbes HTTP seront utilisés quand cela est possible pour définir une opération :
  • PUT pour une mise à jour d'une entité complète, ou pour une opération idempotente
  • POST pour une création d'entité, ou pour opération non idempotente
  • PATCH pour une mise à jour partielle d'une entité(POST pour une création, PUTpour une mise à jour, GET pour une lecture. Quand cela n'est pas possible, on utilisera un segment $action.
• Les routes retournant des listes d'éléments ne doivent en aucun cas retourner directement des tableaux. Il faut pour cela utiliser la structure de donnée prévue à cet effet IPublicHttpResponseQuery. Tous les types de retour sans exception doivent étendre IPublicHttpResponseData de façon à permettre l'intégration de diagnoses dans les réponses.
• Tous les types (paramètres d'entrée ou types de retour) doivent être déclarés (et documentés) dans le paquet @ubstream/ubstream-node-client-sdk.
• Toutes les routes doivent retourner un StatusCode adapté ; il faut utiliser les types fournis par typescript-rest:
  • Return.NewResource (201) pour les créations.
  • Return.Accepted (202) pour les requêtes qui déclenchent des traitements asynchrones.
  • void pour un 204
  Note : Penser à renseigner le header location des réponses pour les cas Return.NewResource et Return.Accepted qui devront réciproquement donner l'URL du get de la ressource créée et l'URL de consultation du status de la requête asynchrone.
• Toutes les routes doivent être documentées avec de la JSDoc.
• Tout ajout de nouvelle route doit être accompagné d'un point d'entrée dans le paquet @ubstream/ubstream-node-client-sdk.
• Toute modification dans l'API doit faire suite à la regénération de la documentation et à la publication du paquet @ubstream/ubstream-node-client-sdk

!!!!! IMPORTANT !!!!!

Aucune route ne doit jamais être modifiée (sauf augmentation). Si un changement cassant doit être introduit, il faudra déclarer un nouveau middleware /v2