Reposant

• basé sur une architecture client-serveur
• et souhaitez servir différents clients via le protocole HTTP
• et souhaitez utiliser les contraintes REST décrites ci-dessus

############################################################################
#                              Movie Apis Definitions                                #
############################################################################
# Code completion support is available so start typing for available options.
swagger: '2.0'

# This is your document metadata
info:
  version: "1.0.1"
  title: The movie api

# Describe your paths here
paths:
  # This is a path endpoint. Change it.
  /movies:
    # This is a HTTP operation
    get:
      # Describe this verb here. Note: you can use markdown
      description: Returns all movies
      operationId: getMovies
      # Expected responses for this operation:
      responses:
        # Response code
        200:
          description: Successful response
          # A schema describing your response object.
          # Use JSON Schema format
          schema:
            title: ArrayOfMovies
            type: array
            items:
               $ref: '#/definitions/movie'
        default:
          description: Error
          schema:
            $ref: 'https://zalando.github.io/problem/schema.yaml#/Problem'
    post:
      description: Add a new movie
      operationId: addMovie
      parameters:
        - name: movie
          in: body
          description: The new movie
          required: true
          schema:
            $ref: '#/definitions/movie'
      responses:
        '201':
          description: The new movie
          schema:
            $ref: '#/definitions/movie'
        default:
          description: Error
          schema:
            $ref: 'https://zalando.github.io/problem/schema.yaml#/Problem'
  /movies/{id}:
    parameters:
      - name: id
        in: path
        description: ID of the movie
        required: true
        type: integer
        format: int64
    get:
      description: Returns a single movie
      operationId: getMovieById
      responses:
        200:
          description: Successful response
          schema:
             $ref: '#/definitions/movie'
        default:
          description: Error
          schema:
            $ref: 'https://zalando.github.io/problem/schema.yaml#/Problem'
    put:
      description: Update an existing movie
      operationId: updateMovieById
      parameters:
        - name: movie
          in: body
          description: The movie
          required: true
          schema:
            $ref: '#/definitions/movie'
      responses:
        '200':
          description: The new movie
          schema:
            $ref: '#/definitions/movie'
        default:
          description: Error
          schema:
            $ref: 'https://zalando.github.io/problem/schema.yaml#/Problem'
    delete:
      description: Delete a movie
      operationId: deleteMovieById
      responses:
        '204':
          description: Movie deleted
        default:
          description: Error
          schema:
            $ref: 'https://zalando.github.io/problem/schema.yaml#/Problem'
definitions:
  movie:
    type: object
    required:
      - id
      - title
    properties:
      id:
        type: integer
        format: int64
      title:
        type: string
      ratings:
        type: object
        properties:
          criticsScore:
            type: integer
            minimum: 0
            maximum: 100
          audienceScore:
            type: integer
            minimum: 0
            maximum: 100
      criticsConsensus:
        type: string
      abridgedDirectors:
        type: array
        items:
          type: string
      abridgedCast:
        type: array
        items:
           $ref: '#/definitions/cast'
      posters:
        $ref: '#/definitions/posters'
  cast:
    type: object
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      characters:
        type: array
        items:
          type: string
  posters:
    properties:
      thumbnail:
        type: string
        format: uri
      profile:
        type: string
        format: uri
      detailed:
        type: string
        format: uri
      original:
        type: string
        format: uri

• Utilisez OAuth2 pour sécuriser votre API.
• Utilisez un jeton Bearer à expiration automatique pour l'authentification ( Authorisation: Bearer f0ca4227-64c4-44e1-89e6-b27c62ac2eb6).
• Exiger HTTPS.
• Envisagez d'utiliser des jetons Web JSON .
• Appliquez l'utilisation des en-têtes Content-Type et Accept-Type même si vous utilisez JSON par défaut pour les requêtes et les réponses.

e.g.  Content-Type: application/json Accept-Type: application/json

• Les réponses contiennent un en-tête :X-Frame-Options: deny

• Niveau 0 : Définissez un URI, et toutes les opérations sont des requêtes POST à ​​cet URI.
• Niveau 1 : Créer des URI distincts pour les ressources individuelles.
• Niveau 2 : Utiliser les méthodes HTTP pour définir les opérations sur les ressources.
• Niveau 3 : Utiliser l'hypermédia (HATEOAS, décrit ci-dessous).

{    
      "healthy": true,   
      "dependencies":
       {         "name": "moviesapi", 
        "healthy": true      
       } 
 }

• Pour une méthode POST, l'URI représente une ressource parente de la nouvelle entité, telle qu'une collection. Par exemple, pour créer un nouveau film, l'URI peut être /api/movies. Le serveur crée l'entité et lui attribue un nouvel URI, tel que /api/movies/6812360. Cet URI est renvoyé dans l'en-tête Location de la réponse. Chaque fois que le client envoie une requête, le serveur crée une nouvelle entité avec un nouvel URI.
• Pour une méthode PUT, l'URI identifie l'entité. S'il existe déjà une entité avec cet URI, le serveur met à jour l'entité existante avec la version dans la demande.

• Cache-Control — Le nombre maximal de secondes (ttl) pendant lesquelles une réponse peut être mise en cache. ( Cache-Control: public, 360ou Cache-Control: no-store)
• Une mise en cache solide minimise le nombre de requêtes reçues par un serveur
• Envisagez une mise en cache faible via l' ETagen-tête de réponse
• ETag — Utilisez un hachage SHA1 pour la version d'une ressource. Assurez-vous d'inclure le type de média dans la valeur de hachage, car cela donne une représentation différente. ( ETag: "2dbc2fd2358e1ea1b7a6bc08ea647b9a337ac92d"). Le client doit envoyer un en-tête If-None-Match pour que ce mécanisme fonctionne.
• Une mise en cache faible minimise le travail qu'un serveur doit faire (mais pas le nombre de requêtes qu'il reçoit)
• Activer la mise en cache basée sur l'en-tête sur tous les proxys et clients (par exemple, NGINX, Apache, APIM) pour augmenter la vitesse et la robustesse
• Aucune donnée compromettant la confidentialité ou la sécurité dans les URL

• Implémenter le chiffrement du contenu sur les points de terminaison les plus éloignés (dans le serveur REST, pas les proxys ou l'APIM)
• Lorsque la signature de contenu est utilisée, cela se fait après que le contenu est (éventuellement) chiffré.
• Utilisez l'en-tête X-Signing-Algorithm pour communiquer le type de signature de contenu ( X-Signing-Algorithm: RS256)
• Utilisez l'en-tête X-SHA256-Checksum pour communiquer la valeur de hachage SHA256 du contenu ( X-SHA256-Checksum: e1d58ba0a1810d6dca5f086e6e36a9d81a8d4bb00378bdab30bdb205e7473f87)
• Utilisez l'en-tête X-Encryption-Algorithm pour communiquer le type de chiffrement de contenu ( X-Encryption-Algorithm: A128CBC-HS256)

• Cohérent (éviter les surprises en étant prévisible)
• Cohésif (répertorie uniquement les points de terminaison avec dépendance fonctionnelle)
• Complète (a tous les points de terminaison nécessaires à son objectif)
• Minimal (pas plus de paramètres que nécessaire pour être complet, pas de fonctionnalité)
• Encapsulation (cacher les détails de mise en œuvre)
• S'expliquer
• Documenté (si l'auto-explication n'est pas suffisante)

• WSO2
• Apigee
• IBM
• Software SA
• Mulesoft