Rédaction d'une spécification OpenAPI 2.0

L'INTERFACE DE PROGRAMMATION D'APPLICATION À TRANSFERT D'ÉTAT REPRÉSENTATIF ou API REST (Representational State Transfer Application Programming Interface) est un moyen conforme à la norme permettant aux applications web de communiquer entre elles à l'aide de méthodes HTTP telles que GET, POST, PUT, DELETE, etc. Elle est conçue autour de ressources, qui peuvent être diverses, allant d'un utilisateur à un fichier. Chaque ressource est identifiée par une URL unique, et les interactions avec ces ressources sont sans état, ce qui signifie que chaque requête d'un client à un serveur doit contenir toutes les informations nécessaires pour comprendre et traiter la requête. Cette caractéristique "sans état", associée à l'utilisation de méthodes HTTP standard, rend API REST hautement évolutive, facile à comprendre et simple à intégrer à différents systèmes. En suivant les principes REST, les développeurs peuvent créer des API cohérentes, faciles à utiliser à l'aide de, et capables de gérer un large éventail de tâches.

InterSystems prend en charge le développement d'API REST à l'aide de divers outils et techniques. Dans cette série d'articles, je vais passer en revue ceux que je préfère personnellement. Les articles sont répartis comme indiqué ci-dessous.

• Rédaction d'une spécification OpenAPI 2.0.
• Documentation et développement d'API REST à l'aide de la spécification OpenAPI 2.0.
• Développement d'un pipeline de production IRIS pour traiter les appels API REST.

Pour suivre les étapes et les instructions décrites dans cette série d'articles, vous devez avoir la configuration suivante.

1. InterSystems IRIS for Health
2. InterSystems IAM avec Dev Portal déployé et activé.
3. Postman ou tout autre logiciel de test d'API.

Supposons que nous développons un flux de travail pour gérer les rendez-vous cliniques. Nous nous concentrerons sur une ressource de rendez-vous et sur la manière de développer des méthodes GET, POST et PUT pour cette ressource. Vous pouvez utiliser les mêmes étapes pour développer une méthode DELETE, mais je ne le ferai pas car je ne le préfère pas vraiment.

Tout d'abord, vous devez commencer par rédiger une spécification OpenAPI 2.0 pour les API de votre application. J'utilise l'éditeur Swagger pour cette tâche afin de pouvoir développer au format YAML, puis je convertis le fichier de spécification au format JSON. Je peux ensuite utiliser le fichier JSON à l'aide des outils de gestion des API IRIS. Vous pouvez utiliser l'éditeur Swagger en ligne gratuitement ou vous pouvez télécharger et déployer un conteneur localement ici: .

Lorsque je crée une spécification OpenAPI, je considère que le fichier comporte trois sections. La section d'introduction est celle où vous présentez l'information descriptive. Elle comprend des champs qui décrivent la nature de l'application, tels que la description, la licence, les balises qui classent les différents points de terminaison et l'URL en combinant l'hôte et l'URL de base. Elle comprend également les limites dans lesquelles elle peut fonctionner, le cas échéant, telles que les schémas et les définitions de sécurité.

Le bloc de code ci-dessous contient un exemple d'introduction qui servira de référence à partir de ce point. Si vous le collez dans un éditeur Swagger ouvert, vous remarquerez que les bases de la documentation API prennent forme.

swagger: "2.0"
info:
  description: "This is a sample server to be as an example Clinic server.  You can find out more about Swagger at [http://swagger.io](http://swagger.io). For this sample, you can use the api key `special-key` or Basic Auth user `Basic` with password `Basic` to test the authorization filters."
  version: "1.0.0"
  title: "Clinic Management"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "raef.youssef@intersystems.com"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "apigatewaydns"
basePath: "/clinic"
tags:
- name: "Scheduling"
  description: "Everything about your Pets"
  externalDocs:
    description: "Find out more"
    url: "http://intersystems.com"
schemes:
- "http"
- "https"
securityDefinitions:
  BasicAuth:
    type: "basic"
    name: "Basic"
  api_key:
    type: "apiKey"
    name: "api_key"
    in: "header"

La deuxième section du fichier de spécifications est le corps. C'est là que vous listez les différents chemins, également appelés points de terminaison, et les méthodes disponibles pour chacun d'entre eux. Pour les besoins de cette démonstration, nous allons simplement composer les spécifications pour le point de terminaison “/appointment”. Ci-dessous, vous trouverez le texte correspondant.

paths:
  /appointment:
    get:
      tags:
        - Scheduling
      summary: "Fetches an existing appointment details"
      security:
      - Basic: []
      description: "Fetches an existing appointment details by providing its ID"
      operationId: "getAppointmentByID"
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "id"
        type: "integer"
        format: "int64"
        description: "ID of the appointment sought"
        required: true
      responses:
        '200':
          description: successful operation
#          schema:
#            $ref: '#/definitions/appointment'
    post:
      tags:
        - Scheduling
      summary: ""
      security:
      - api_key: []
      description: ""
      operationId: "postAppointment"
      consumes:
      - "application/json"
      - "application/xml"
      produces:
      - "application/json"
      - "application/xml"
      parameters:
      - in: "formData"
        name: "Date"
        type: "string"
        format: "date-time"
        description: ""
        required: true
      - in: "formData"
        name: "duration"
        type: "integer"
        format: "int64"
        description: "number of half hour slots of the appointment duration"
        required: true
      responses:
        '200':
          description: successful operation
        '405':
          description: Time not available
    put:
      tags:
        - Scheduling
      summary: ""
      security:
      - BasicAuth: []
      description: ""
      operationId: "updateAppointment"
      consumes:
      - "application/json"
      - "application/xml"
      produces:
      - "application/json"
      - "application/xml"
      parameters:
      - in: "query"
        name: "id"
        type: "integer"
        format: "int64"
        description: "ID of the appointment sought"
        required: true
      - in: "body"
        name: "body"
        description: ""
        required: true
#        schema:
#          $ref: "#/definitions/appointment"
      responses:
        '200':
          description: successful operation
        '405' :
          description: Time not available
        '406' :
          description: Appointment Not Found

Il convient de remarquer quelques aspects dans la section des chemins d'accès. Tout d'abord, vous pouvez attribuer un mécanisme d'authentification différent pour chaque méthode. Le champ "OperationID" permet d'identifier le processus backend à l'aide duquel une méthode respective est appelée. De plus, vous pouvez définir un schéma pour le corps JSON d'une requête et pour la réponse. Il est commenté ici afin d'éviter toute erreur lors du collage, car nous n'avons pas encore défini ce schéma. Enfin, vous pouvez définir des codes de réponse et des messages personnalisés.

La dernière section est celle où sont définis les différents schémas de messages. Dans cet exemple, nous allons composer le schéma de rendez-vous afin d'inclure l'ID du rendez-vous, la date, la durée et le nom du prestataire de services. Vous trouverez ci-dessous le texte de la définition YAML. Après avoir collé ce qui suit dans votre éditeur, vous pouvez décommenter les lignes où la définition du schéma est référencée.

definitions:
    appointment:
        type: "object"
        properties:
            id:
                type: "integer"
                format: "int64"
            Provider:
                type: "string"
                format: "string"
            Date:
                type: "string"
                format: "date-time"
            Duration:
                type: "integer"
                format: "int64"

Cette partie de la série est maintenant terminée. Nous utiliserons cette spécification dans les prochains articles de la série. Ils seront bientôt disponibles, alors restez connectés. Pour plus d'information sur le développement de la spécification OpenAPI 2.0, veuillez vous reporter à la documentation ici .