octo-woapi / cookbook

List of API good practices

API Cookbook

Recipes for cooking complex API meals

Web app

https://octo-woapi.github.io/cookbook/

Status

In active development.

Stack

Development: VuePress, Vuetify
CI: Travis

How to add content?

TL;DR

• Create a branch recipe-x
• Add content
• Open up a pull request

Done!

Longer story

This website uses VuePress to build .vue and .md files.
The addition of a page consists of several steps:

• create a branch from master named recipe-x where x is the subject of your recipe
• create a file recipes/<your-file>.md
• add some content ; you can preview your changes using yarn serve
• when you are done, push your changes to git and open a pull request
• [if any] treat the review comments

Every pull request triggers a workflow that checks if the app is correctly built. When your pull request is accepted, the CI builds and checks if everything is ok. The changes are deployed onto gh-pages and available to readers after that.

Contributing

cookbook's Issues

Upload d'une image

Quel design pour une ressource qui comporte des champs json (metadata de l'image) et une image ?

Quelques pistes :

• transformer l'image en base64 et l'envoyer dans un champ string dans le json
  • => problème de la conversion et de l'ajout de 30% de poids en plus
  • mais ça permet de n'avoir qu'un seul appel pour les metadata + le fichier, et on reste sur de la manipulation de string donc plus "simple" que du binaire
  • => à déconseiller ou réserver aux petites images
• faire deux ressources séparées : un premier appel pour créer la ressource avec du json, et un 2e pour uploader juste l'image avec le content type style image/png
  • genre POST /maresources + PUT /maresources/123/image
• utiliser le content-type multipart/form-data, comme un formulaire web classique
  • avantage : on peut avoir le fichier + les metadata en un seul appel
  • on peut uploader plusieurs fichiers en un seul appel
  • réserves : est-ce encore du REST ? facilité d'utilisation : à voir suivant les clients http, mais ça peut perturber les consommateurs

Sources :

• https://stackoverflow.com/questions/33279153/rest-api-file-ie-images-processing-best-practices
• https://phil.tech/2016/http-rest-api-file-uploads/
• une bonne explication du multipart : https://www.outsystems.com/blog/posts/consuming-multipart-form-data-rest-method/
• swagger multipart : https://swagger.io/docs/specification/describing-request-body/multipart-requests/
• https://blogs.infinitesquare.com/posts/web/gerer-les-requetes-multipart-avec-du-json-et-des-uploads-en-aspnet-core

Exemple multipart avec Spring + Swagger :

@ApiOperation("Test multipart")
@PostMapping("test", consumes = [MULTIPART_FORM_DATA_VALUE], produces = [APPLICATION_JSON_VALUE])
fun test(
    @RequestParam name: String,
    @RequestPart document: MultipartFile
): Unit = TODO()

ça s'affiche correctement dans swagger :

Mise à jour partielle d'une ressource

cf Article de blog
https://blog.octo.com/should-i-put-or-should-i-patch/

Créer une ressource dont l'ID est déjà généré (ex: créé par l'app front)

Quel design aurais-je ?

Modifier le status d'une ressource : put, patch, delete ? Verbe ou pas verbe ?

je rédige asap

Gestion des erreurs : ne pas en dévoiler trop (403 vs 404)

Des erreurs trop détaillées peuvent introduire des failles de sécu en donnant trop d'infos.

exemple :
GET /a/123/b/456
=> 404 "A not found" => a n'existe pas
=> 404 "b not found" => a existe mais pas b
=> 403 : a et b existent

Documentation auto-générée

Ex: swagger, redoc...

i18n - Ajouter le français

Je pense qu'il serait intéressant de laisser le choix au lecteur du cookbook de choisir entre les recettes en anglais et français.
Sachant que nous avons principalement une audience française sur le blog.

Mise à jour de plusieurs ressources (transaction distribuée)

Design API d'une transaction

Ex: transaction bancaire
Si je fais un virement d'un compte A à un compte B, comment est représenté ce virement ?
Avec plusieurs appels, ou un seul appel ?
Que se passe-t-il si un appel fail ? Comment est géré le rollback ?

Cache API (ETag, Cache-Control, Pragma...)

Expliquer les bonnes pratiques sur les headers de cache api à positionner

Utiliser l'article du blog :
https://blog.octo.com/en/cache-me-if-you-can-1/

Choisir son status code en cas de succès

Gestion de la pagination

Gestion des ID de ressources

Quel type d'ID choisir ? Pourquoi ?
(Integer/String/Uuid/Login/Username/Email)

(quand en faire, ou pas, quoi choisir, quid du cas façade d’un système sous jacent (qui a ses propres ID, ou pas d’IDs...)) => https://matthiasnoback.nl/2018/05/when-and-where-to-determine-the-id-of-an-entity/

Existence d'une ressource

Quel design API utilisé pour créer une route renvoyant l'existence ou non d'une ressource ?

GET ? HEAD ? (https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.2)

Réparer le déploiement du cookbook

Réparer le déploiement du cookbook
(cassé depuis juin 2021)

Il semblerait que ce soit lié à la migration de travis

"Since June 15th, 2021, the building on travis-ci.org is ceased. Please use travis-ci.com from now on."

Il faut reconfigurer la CI.

30/07: Changement de CI, Travis CI => Github Actions

Choisir son status code pour les erreurs

Quand tu crée une resource avec un post mais que tu as plusieurs erreurs
il manque une date (400) tu fais référence à un id qui n'existe pas (400 ou 404) ?
La réponse donnée avait été, 400 dans tous les coups
il y a également alain fauré qui a posé une question récemment je crois, et RED avait apporté une réponse

400 pour les erreurs techniques, 422 pour les erreurs métier

Cf mail de RED avec Alain fauré

Déploiement

Le déploiement automatique ne fonctionne plus puisque je ne fais plus partie de l'orga WOAPI. Mon token n'est plus autorisé donc le build ne s'effectue plus.

Il faut :

• créer un compte sur travis-ci.com et autoriser le build pour ce repo ;
• regénérer un token pour déployer sur GitHub Pages ;
• insérer ce token dans le fichier .travis-ci.yml ;
• lancer un déploiement.

Amélioration UI (Jolifier)

Proposition d'UI:
Favicon
Header/Footer
Fil d'ariane (arbre de navigation)
Utiliser le design system Octo

Gestion d'un panier d’achat

Design d'un panier d'achat

Comment créer/alimenter un panier d'achat ?

Versionner une API

Cf Article blog Octo sur le versioning
https://blog.octo.com/designer-une-api-rest/#versioning

"Non-resource" scenario

Faire une action dans API sans créer de ressource ?

Cf Blog Octo Design API / slide SAPI1
https://blog.octo.com/designer-une-api-rest/#non_resources

Ajouter de liens vers des ressources externes

Hello,

Je pense qu'il serait intéressant d'ajouter des liens dans les cookbooks vers des articles de blogs, livres, vidéos, documentation API ou autres ressources permettant d'illustrer ou bien creuser le sujet abordé.

Exemple : dans le cookbook error format, ça donnerait de la crédibilité au discours de voir des exemples d'entreprises qui le font dans la vraie vie

Améliorer le design du site

Le site est super basique.
Le markdown s'affiche parfois bizarrement.
Voir ce qu'on peut faire pour améliorer.

Traitement asynchrone via API

Solution 1 :

• Route pour création de la ressource
• Renvoi du code HTTP 206 + Identifiant de la ressource
• Route pour suivre l'avancement du traitement
• le client fait du long polling

Solution 2 :

• Route pour création de la ressource
• Le client doit fournir une URL de callback
• le serveur fait appel au client une fois le traitement terminé

Ex:
https://www.mscharhag.com/api-design/rest-asynchronous-operations