Au programme

1. Le problèmePourquoi les contrats d'API ne suffisent pas5 min
2. ArazzoDéfinition, état des lieux, lire un fichier15 min
3. Un exempleUn parcours complet, avec dependsOn10 min
4. Une hypothèseMicrocks V2, sur prototype10 min
5. ÉchangeVotre avis, vos parcours5 min

En sortant, vous saurez ce qu'est Arazzo, lire un fichier, et vous aurez donné votre avis sur une idée.

Une souscription habitation s'appuie sur 3 contrats d'API.
Le parcours qui les enchaîne, lui, n'est décrit nulle part.

Dans quel ordre appeler ? Quelle donnée passe d'un appel au suivant ? Que faire si un appel échoue ? Aujourd'hui : un wiki, un diagramme de séquence qui vieillit, ou la tête d'un architecte.

Des contrats d'API par service, aucun pour le parcours

Arazzo, c'est quoi ?

Une norme de l'OpenAPI Initiative (Linux Foundation) pour décrire, en YAML ou JSON, une suite d'appels d'API : leur ordre, les données qui passent de l'un à l'autre, et ce qui fait qu'une étape est réussie.

arazzo « tapisserie » en italien — on tisse des API existantes en un parcours.

Ce qu'Arazzo est — et ce qu'il n'est pas

Trois normes, trois questions

Arazzo ne remplace rien : il référence

Corollaire : pas de contrat OpenAPI/AsyncAPI à jour, pas d'Arazzo.

Une norme jeune, une famille mature

Même gouvernance qu'OpenAPI : OpenAPI Initiative, Linux Foundation.

Anatomie : chaque bloc répond à une question

Les expressions : le fil qui relie les étapes

À retenir : $steps.…outputs rend explicite ce qu'on se transmet entre équipes.

Du devis à la police, en un workflow

Le fichier : sources et premières étapes

arazzo: 1.1.0
sourceDescriptions:                                       # les contrats d'API, référencés
  - { name: quoteApi,   type: openapi, url: ./quote-api.openapi.yaml }
  - { name: paymentApi, type: openapi, url: ./payment-api.openapi.yaml }
  - { name: policyApi,  type: openapi, url: ./policy-api.openapi.yaml }
workflows:
  - workflowId: identifierClient                            # étapes non détaillées ici
  - workflowId: souscrireHabitation
    dependsOn: [ identifierClient ]                         # un parcours prérequis
    steps:
      - stepId: creerDevis
        operationId: $sourceDescriptions.quoteApi.createQuote
        requestBody:
          payload: { customerId: $workflows.identifierClient.outputs.customerId }
        successCriteria: [ { condition: $statusCode == 201 } ]
        outputs: { quoteId: $response.body#/id }
      - stepId: verifierEligibilite
        operationId: $sourceDescriptions.quoteApi.checkEligibility
        parameters: [ { name: id, in: path, value: $steps.creerDevis.outputs.quoteId } ]
        successCriteria: [ { condition: $response.body#/eligible == true } ]

dependsOn : un prérequis écrit dans le contrat

- stepId: payer
  operationId: $sourceDescriptions.paymentApi.pay
  # prérequis explicite. Selon la spec Arazzo,
  # en synchrone l'ordre de steps suffit : dependsOn
  # sert surtout à l'asynchrone (voir annexe).
  dependsOn: [ verifierEligibilite ]   # jamais avant
  requestBody:
    payload: { quoteId: $steps.creerDevis.outputs.quoteId }
  successCriteria: [ { condition: $statusCode == 201 } ]
  onFailure:
    - { name: indispo, type: retry,
        retryAfter: 2, retryLimit: 3,
        criteria: [ { condition: $statusCode == 503 } ] }
  outputs: { paymentId: $response.body#/id }
- stepId: emettrePolice
  operationId: $sourceDescriptions.policyApi.issuePolicy
  successCriteria: [ { condition: $statusCode == 201 } ]
  outputs: { policyId: $response.body#/policyId }

Pourquoi y aller — et ce qui peut coincer

L'idée : un fichier, deux façons de vérifier

Microcks lirait le workflow

Prototype

Ce qu'on voit

• Le fichier Arazzo importé, relié à ses contrats d'API.
• Les étapes REST et événement dans un même diagramme.
• Les données qui circulent : orderId → correlationId.
• Les critères de succès de chaque étape.

Pour l'architecte

Le parcours devient visible et revu, pas seulement dessiné.

Microcks vérifierait les appels reçus

Prototype

Ce qu'on voit

• L'application a appelé les mocks Microcks.
• Microcks compare ces appels au workflow Arazzo.
• Verdict : échec, le paiement a été appelé avant la réservation de stock — exactement un prérequis de type dependsOn.
• L'étape fautive, la requête et la réponse sont affichées.

Pour le QA et le dev

Un verdict qui pointe l'étape, pas un log de 3 000 lignes.

Un fichier, trois métiers : votre avis

L'étape événementielle

- stepId: attendrePoliceEmise
  operationId: $sourceDescriptions.policyEvents.onPolicyIssued
  action: receive
  dependsOn: [ payer ]
  correlationId: $steps.payer.outputs.paymentId
  timeout: 30000                  # ms
  successCriteria:
    - context: $message.payload
      condition: $.status == 'ISSUED'
      type: jsonpath
  outputs:
    policyId: $message.payload.policyId