Incaya
INCAYA est une Société COopérative et Participative (une SCOP) caennaise, spécialisée dans le numérique
https://www.caen.camp/talks/openapi-un-contrat-pour-vos-apis
@caencamp
https://www.caen.camp/talks/edition-28-le-graphql-cest-vraiment-la-fin-du-rest
Wikipedia : "En informatique, une interface de programmation d’application ou interface de programmation applicative (souvent désignée par le terme API pour Application Programming Interface) est un ensemble normalisé de classes, de méthodes, de fonctions et de constantes qui sert de façade par laquelle un logiciel offre des services à d'autres logiciels."
Wikipedia : "REST (representational state transfer) est un style d'architecture logicielle définissant un ensemble de contraintes à utiliser pour créer des services web. Les services web conformes au style d'architecture REST, aussi appelés services web RESTful, établissent une interopérabilité entre les ordinateurs sur Internet. Les services web REST permettent aux systèmes effectuant des requêtes de manipuler des ressources web via leurs représentations textuelles à travers un ensemble d'opérations uniformes et prédéfinies sans état."
* l’URI comme identifiant des ressources
* les verbes HTTP comme identifiant des opérations
(GET, POST, PUT, PATCH, DELETE)
* les réponses HTTP comme représentation des ressources
(* Create Read Update Delete)
- Liste des joueurs.euses -
=> GET - https://api.domain/players
- Créer un joueur.euse -
=> POST - https://api.domain/players
- Informations sur un joueur.euse -
=> GET - https://api.domain/players/playerId
- Mettre à jour les informations sur un joueur.euse -
=> PUT - https://api.domain/players/playerId
- Supprimer un joueur.euse -
=> DELETE - https://api.domain/players/playerId
Mais ...
1 ) Quel sera le format le formatage de la représentation de la ressource retournée dans le corps de la réponse http ?
Postulons que l'on utilisera l'en tête http content-type pour demander un format json
2) Ce que signifierons les données retournées dans le documents json
3) Quels seront les liens entre les différents objets retournés
4) Comment naviguer au sein de l'API au delà de la simple logique du Rest
(sémantique)
Wikipedia : "JSON-LD, ou JavaScript Object Notation for Linked Data, est une méthode permettant d'encoder des données structurées (en anglais linked data) en utilisant du JSON."
C'est une recommandation du W3C depuis 2014
{
"id": "valquirit",
"name": "Valquirit",
"number": 75,
"picture": "http://rdc.fr/pictures/RDC_B_75-Valquirit.jpg",
}
{
"@context": "http://schema.org",
"@type": "Person",
"identifier": "valquirit",
"name": "Valquirit",
"number": 75,
"image": "http://rdc.fr/pictures/RDC_B_75-Valquirit.jpg",
}
=> GET - https://api.domain/players/valquirit
Les données structurées vues par google
La décentralisation des données vue par Tim Berners-lee (Solid)
Level 3
=
HATEOAS
ou
Hypermedia As The Engine Of Application State
Mais HATEOAS n'est qu'une contrainte d'architecture.
[
{
"number": 187,
"picture": "http://rdc.fr/pictures/RDC_B_187-Rice-Cooker-.jpg",
"id": "rice-cooker",
"name": "Rice Cooker"
},
{
"number": 171,
"picture": "http://rdc.fr/pictures/RDC_B_171-Claraclette.jpg",
"id": "claraclette",
"name": "Claraclette"
}
]
=> GET - https://api.domain/players?pagination=[2-2]
{
"meta": {
"totalPages": 9
},
"data": [
{
"type": "player",
"id": "rice-cooker",
"attributes": {
"number": 187,
"picture": "http://rdc.fr/pictures/RDC_B_187-Rice-Cooker-.jpg",
"name": "Rice Cooker"
}
},
{
"type": "player",
"id": "claraclette",
"attributes": {
"number": 171,
"picture": "http://rdc.fr/pictures/RDC_B_171-Claraclette.jpg",
"name": "Claraclette"
}
}
],
"links": {
"self": "https://api.domain/players?pagination[2-2]",
"first": "https://api.domain/players?pagination[1-2]",
"prev": "https://api.domain/players?pagination[1-2]",
"next": "https://api.domain/players?pagination[4-2]",
"last": "https://api.domain/players?pagination[9-2]"
}
}
Linked-data
Hypermedia
- HATEOAS -
JSON-LD
OpenAPI est une spécification permettant d'écrire un fichier(en json ou en yaml)
qui va permettre de
décrire, produire, consommer et visualiser un services Web REST.
Ce fichier, complètement indépendant des documents servis par l'API, va constituer
openapi: 3.0.2
info:
version: 1.0.0
title: The famous Roller Derby API
contact:
email: contact@alexisjanvier.dev
security: []
servers: []
tags:
- name: my tag
paths: {}
components:
securitySchemes: {}
schemas: {}
parameters: {}
info:
version: 1.0.0
title: The Famous Roller Derby API - FRDA
description: >-
Trouver toutes les informations sur les équipes
et les matchs de Roller Derby en Europe.
![Roller Derby](https://roller-derby.io/logo.png)
termsOfService: https://roller-derby.io/api/terms/
contact:
name: FRDA Support
url: https://roller-derby.io/api/support
email: api@roller-derby.io
license:
name: GNU GPLv3
url: https://roller-derby.io/api/LICENSE
components:
securitySchemes: {}
schemas:
Player:
description: "Un.e joueur.euse de Roller Derby"
type: object
properties:
id:
type: string
readOnly: true
name:
type: string
number:
type: integer
picture:
type: string
parameters: {}
Player:
description: "Un.e joueur.euse de Roller Derby"
type: object
properties:
id:
type: string
readOnly: true
name:
type: string
minLength: 3
maxLength: 50
number:
type: integer
maximum: 9999
format: int32
picture:
type: string
nullable: true
required:
- id
- name
- number
- picture
paths:
/players:
get:
description: Retourne la liste des tous.tes les joureurs.euses.
operationId: getPlayerList
tags:
- Players
parameters:
- name: pagination
in: query
description: Pagination parameters.
required: false
schema:
type: string
example: "[10,3]"
- name: filters
$ref: "#/component/parameters/Filters"
responses:
"200":
...
put:
...
delete:
...
paths:
/players:
get:
description: Retourne la liste des tous.tes les joureurs.euses.
operationId: getPlayerList
tags:
- Players
parameters:
...
responses:
"200":
description: Une liste de joueurs.euses.
content:
application/json:
schema:
type: array
items:
$ref: "#/component/schemas/Player"
examples:
shortList:
summary: Une courte liste de un joueur.euse
value: >-
[
{
"number": 187,
"picture": "http://roller-derby-caen.fr/wp-content/uploads/2019/12/RDC_B_187-Rice-Cooker-.jpg",
"id": "rice-cooker",
"name": "Rice Cooker",
},
]
put:
...
Player:
get:
description: Informations sur un.e joueur.euse.
operationId: getPlayer
tags:
- Players
parameters:
- name: playerId
$ref: "#/component/parameters/PlayerId"
responses:
"200":
description: Le.a joueur.euse demandé.e.
content:
application/json:
schema:
$ref: "#/component/schemas/Player"
Player:
get:
operationId: getPlayer
parameters:
- name: playerId
$ref: "#/component/parameters/PlayerId"
responses:
"200":
description: Le.a joueur.euse demandé.e.
content:
application/json:
schema:
allOf:
$ref: "#/component/schemas/Person"
$ref: "#/component/schemas/Player"
puis de reconstituer un unique fichier avec des outils comme swagger-cli
➜ tree openapi -L 2
openapi
├── index.yaml
├── openapi.json
├── package.json
├── package-lock.json
├── paths
│ ├── index.yaml
│ └── players.yaml
└── schemas
├── index.yaml
└── player.yaml
Par exemple Eslint et Prettier prennent en charge le yaml et le json. Il existe un plugin ESLINT openapi.
Il existe aussi des outils permettant de valider la sécurité de son API d'après son contrat openapi : APISecurity.io
Comme Swagger editor ou StopLight Studio
Rapprochement avec le vocabulaire JSON Schema.
Par exemple, on trouve express-openapi-validator pour réaliser en "live" une validation des objets `request` et `response` d'une API codée avec Express.js.
On trouve :
Ce n'est pas un standard
C'est très long et très fastidieux à écrire
By Incaya
Après avoir isolé OpenAPI au sein de la jungle des acronymes liés au REST (JSON-LD, HATEAOS, Hydra, JSON-API, …), nous verrons ce que dit cette spécification sur ce que peut-être un contrat d’API. Nous verrons ensuite ce que l’on peut faire d’un tel contrat et enfin ses avantages et ses inconvénients.
INCAYA est une Société COopérative et Participative (une SCOP) caennaise, spécialisée dans le numérique