Développement API (web API/RESTful API)

• Développement API (web API/RESTful API)
  • Démos
    • Démo youtypeitwepostit
    • Démos du cours
  • Exercices et corrections
  • Kit de démarrage complet pour développer son API
  • Outils
    • Clients HTTP
  • Références
    • Ouvrages
    • Conférences (YouTube)
    • Articles sur le web, les systèmes hypertextes et les services RESTful
    • Sur le cache HTTP
    • RFC (Request For Comments) intéressantes et utilisées
    • Spécifications de structures de représentations/messages ou media types
    • Sur la sémantique des hypermédias (vocabulaires, actions)

Démos

Liste des démos (mini projets pour présenter un ou plusieurs concepts)

Démo youtypeitwepostit

Disponible sur ce dépôt.

• Télécharger le code source
• Lancer la démo :

#A la racine du projet
node server/app.js

Démos du cours

• Accéder aux démos JS/Node.js/Express.js
• Accéder à la démo architecture RPC vs ROA
• Accéder à la démo JWT en vanilla PHP
• Accéder à la démo live de l'implémentation du service de billetterie de concerts. Cette démo est "en l'état"
• Accéder à la démo de sécurisation du service (anti brute force sur login, gestionnaire de processus et autres)

Exercices et corrections

• Suggestion conception d'API
• Suggestion JS/Node.js/Express.js

Kit de démarrage complet pour développer son API

• Starter pack: RESTful web API avec Node.js, Express.js, MySQL et Adminer, un starter pack dockerisé d'une application web Node.js pour développer une web API RESTful. En plus d'un service Node.js pour développer son application/API, le pack vient avec un service de base de données relationnelles (MySQL) et un gestionnaire de base de données graphique (Adminer).

Outils

Clients HTTP

• cURL, un outil en ligne de commande pour le transfert de données via des URL. Peut être utilisé comme un client HTTP. Attention, cURL sur Windows et cURL sur les systèmes UNIX (GNU/Linux et macOS) ne sont pas implémentées pareil et ont des options différentes. Tous les exemples de cURL sur le dépôt et dans les supports de cours sont au format UNIX (à adapter pour Windows si besoin), sinon installer la WSL et utiliser cURL depuis votre instance GNU/Linux
• Sur Windows, Invoke-RestMethod, un client HTTP intégré à PowerShell. Ouvrir une invite de commande PowerShell pour l'utiliser
• Extension VScode Thunder Client, une extension pour effectuer des reqûetes HTTP et gérer des collections de requêtes depuis VS Code
• Extension VSCode REST client, une extension pour effectuer des reqûetes HTTP et gérer des collections de requêtes depuis VS Code, plus minimaliste mais efficace
• Postman, l'artillerie lourde. Nécessite de créer un compte
• Swagger UI, servir de la documentation et de quoi tester son API directement sur son service web (voir Exercice 2 et starter-pack)

Références

Ouvrages

• RESTful Web Services, de Leonard Richardson, Sam Ruby, O'Reilly, 2007 S'il y a un livre à lire/étudier/feuilleter/avoir c'est celui-ci, must have. Il commence à dater mais reste très profond et intéressant. Ce livre est passé sous licence Creative Commons dans le cadre du projet O'Reilly Open Books. Accéder à la version en ligne/PDF gratuite LP++
• RESTful Web APIs, de Leonard Richardson, Mike Amundsen, Sam Ruby, O'Reilly, 2013. Une version actualisée, rafraîchie de RESTful Web Services; LP++
• REST API Design Rulebook, de Mark Masse, O'Reilly, 2011. LI+
• RESTful Web API Patterns and Practices Cookbook, de Mike Amundsen, O'Reilly, 2022. Introduction un peu plus obscure, synthétique (mais intéressante !) que les livres de Richardson et al., se concentre sur les problèmes/solutions (comme son titre l'indique). Très précieux pour mettre en application ce que l'on a appris de Richardson, sur des cas concrets, complexes et réels. LP+;
• RESTful Web Clients, de Mike Amundsen, O'Reilly, 2017. LE++
• REST API Development with Node.js : Manage and Understand the Full Capabilities of Successful REST Development, 2nd Edition, de Fernando Doglio, Apress, 2018
• Bien architecturer une application REST, par Olivier Gutknecht, avec la contribution de Jean Zundel, Eyrolles, 2009

Conférences (YouTube)

• Boostez vos applications avec HTTP/2 - Kévin Dunglas - Forum PHP 2018
• Performance Optimization - Fabien Potencier - PHP Tour 2016
• Same-origin policy: The core of web security @ OWASP Wellington, excellente présentation de Kirk Jackson de la Same Origin Policy avec démonstrations à l'appui. À regarder.
• Alan Kay - The computer revolution hasnt happened yet (1997), conférence d'Alan Kay lors de l'OOPLSA 1997 à Atlanta. Sur le design de systèmes complexes qui durent dans le temps et l'ambition initiale de la programmation "orientée objet" (ou processus). Remarquez la ressemblance entre les objets de Kay et le réseau de services RESTful de Fielding.

Articles sur le web, les systèmes hypertextes et les services RESTful

• REST APIs must be hypertext-driven, billet de blog de Roy T. Fiedling très intéressant sur le fait qu'une API RESTful doit être orientée hypertexte (ou de manière générale hypermédias)
• W3C: Cool URIs don't change, par Tim Berners-Lee
• The Vision of Kay and Fielding: Growable Systems that Last for Decades
• W3C: Architecture of the World Wide Web, Volume One, écrit par le W3C Technical Architecture Group: Tim Berners-Lee (co-Chair, W3C), Tim Bray (Antarctica Systems), Dan Connolly (W3C) et al.. Une bible sur l'architecture du web
• REST, une synthèse de David Gayerie sur REST de grande qualité, avec une bibliographie utile
• Welcome to the REST CookBook, portail sur différents aspects de REST, How to do stuff RESTful
• Zalando RESTful API and Event Guidelines, guide sur ce que votre API doit, devrait ou pourrait faire (must, should, may). Pour vous aider à placer le marqueur sans renoncer à construire un système hypermédia
• The stateless blog, de Mike Kelly. Quelques billets intéressants :
  • JSON Linking with HAL;
  • The case for hyperlinks in APIs
• Services web, très bon article Wikipédia sur les services web et les différentes architectures
• Fielding, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation, University of California, Irvine, 2000., la thèse de Roy qui a "coin" le terme REST. La thèse de Roy Fielding sur l'architecture logicielle distribuée et comment construire et faire évoluer des grands systèmes complexes. Voir la traduction Chapitre 5 sur REST en français par exemple

Sur le cache HTTP

• HTTP Caching, une synthèse sur l'implémentation du cache du protocole HTTP. Attention, tous les navigateurs n'implémentent pas le standard au même point.
• Un tutoriel sur la mise en cache du protocole HTTP, un très bon tutoriel en français sur la mise en cache du protocole HTTP

RFC (Request For Comments) intéressantes et utilisées

Documents à l'origine des standards du web. Vous êtes encouragé·es à les parcourir

• RFC3986: Uniform Resource Identifier (URI): Generic Syntax, T. Berners-Lee (W3C/MIT), R. Fielding (Day Software), L. Masinter (Adobe Systems)
• JSON Hypertext Application Language draft-kelly-json-hal-08, HAL representation pour les modèles de données. Une proposition de standard
• RFC 9068: JWT Profile for OAuth 2.0 Access Tokens, la RFC du standard JWT
• RFC 9110: HTTP Semantics, la RFC sur la sémantique du protocole HTTP (sémantique des verbes, headers, concepts). La source

Spécifications de structures de représentations/messages ou media types

• HAL, les différents types d'hypermédia définis pour le protocole HTTP et pour construire des API plus robustes. Le livre de l'auteur Building Hypermedia APIs with HTML5 and Node, Amundsen, a l'air très intéressant;
• SIREN,
• Collection+JSON
• IANA Media Types Registry, liste de formats sérieux, recensés par l'IANA. Si vous cherchez un format pour les réponses de votre service vous pouvez parcourir cette liste.

Sur la sémantique des hypermédias (vocabulaires, actions)

• Resource Description Framework, a pour but de décrire formellement les ressources Web et leurs métadonnées, afin de permettre le traitement automatique de ces descriptions. Développé par le W3C, RDF est le langage de base du Web sémantique;
• Schema.org, Schema.org is a collaborative, community activity with a mission to create, maintain, and promote schemas for structured data on the Internet. Propose une liste de vocabulaires standardisés à suivre pour différents modèles de données;
• Microformats wiki, un wiki qui décrit des spécifications de structure de données interopérables:
• JSON-LD 1.1, A JSON-based Serialization for Linked Data, une spécification de représentation standardisée des données soutenue et recommandée par le W3C. Fait partie du projet Hydra. Vocabulaire standardisé
• Hydra Core Vocabularies, soutenue et recommandée par le W3C Hydra is an effort to simplify the development of interoperable, hypermedia-driven Web APIs. The two fundamental building blocks of Hydra are JSON‑LD and the Hydra Core Vocabulary. Décrit des ressources, leurs types et leurs propriétés, ainsi que les opérations (actions) qui peuvent être effectuées sur ces ressources. Actions standardisées