Erholsam

• basierend auf einer Client-Server-Architektur
• und verschiedene Clients über das HTTP-Protokoll bedienen möchten
• und die oben beschriebenen REST-Einschränkungen verwenden möchten

############################################################################
#                              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

• Verwenden Sie OAuth2 , um Ihre API zu sichern.
• Verwenden Sie ein automatisch ablaufendes Bearer-Token für die Authentifizierung ( Authorisation: Bearer f0ca4227-64c4-44e1-89e6-b27c62ac2eb6).
• HTTPS erforderlich.
• Erwägen Sie die Verwendung von JSON Web Tokens .
• Erzwingen Sie die Verwendung der Header „Content-Type“ und „Accept-Type“, auch wenn Sie JSON als Standard für Anforderungen und Antworten verwenden.

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

• Antworten enthalten Header:X-Frame-Options: deny

• Ebene 0: Definieren Sie einen URI, und alle Vorgänge sind POST-Anforderungen an diesen URI.
• Stufe 1: Erstellen Sie separate URIs für einzelne Ressourcen.
• Stufe 2: Verwenden Sie HTTP-Methoden, um Operationen für Ressourcen zu definieren.
• Stufe 3: Verwenden Sie Hypermedia (HATEOAS, unten beschrieben).

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

• Bei einer POST-Methode stellt der URI eine übergeordnete Ressource der neuen Entität dar, z. B. eine Sammlung. Um beispielsweise einen neuen Film zu erstellen, könnte der URI /api/movies. Der Server erstellt die Entität und weist ihr einen neuen URI zu, z. B. /api/movies/6812360. Dieser URI wird im Location-Header der Antwort zurückgegeben. Jedes Mal, wenn der Client eine Anfrage sendet, erstellt der Server eine neue Entität mit einem neuen URI.
• Bei einer PUT-Methode identifiziert der URI die Entität. Wenn bereits eine Entität mit diesem URI vorhanden ist, aktualisiert der Server die vorhandene Entität mit der Version in der Anforderung.

• Cache-Control – Die maximale Anzahl von Sekunden (ttl), die eine Antwort zwischengespeichert werden kann. ( Cache-Control: public, 360oder Cache-Control: no-store)
• Starkes Caching minimiert die Anzahl der Anfragen, die ein Server erhält
• Erwägen Sie schwaches Caching durch den ETagResponse-Header
• ETag – Verwenden Sie einen SHA1-Hash für die Version einer Ressource. Stellen Sie sicher, dass Sie den Medientyp in den Hash-Wert aufnehmen, da dies eine andere Darstellung ergibt. ( ETag: "2dbc2fd2358e1ea1b7a6bc08ea647b9a337ac92d"). Der Client muss einen If-None-Match- Header senden, damit dieser Mechanismus funktioniert.
• Schwaches Caching minimiert die Arbeit, die ein Server erledigen muss (aber nicht die Anzahl der Anfragen, die er erhält)
• Aktivieren Sie Header-basiertes Caching auf allen Proxys und Clients (z. B. NGINX, Apache, APIM), um die Geschwindigkeit und Robustheit zu erhöhen
• Keine den Datenschutz oder die Sicherheit gefährdenden Daten in URLs

• Implementieren Sie die Inhaltsverschlüsselung an den entferntesten Endpunkten (im REST-Server, nicht in den Proxys oder APIM)
• Wenn die Inhaltssignierung verwendet wird, erfolgt dies, nachdem der Inhalt (optional) verschlüsselt wurde.
• Verwenden Sie den X-Signing-Algorithm-Header, um die Art der Inhaltssignierung zu kommunizieren ( X-Signing-Algorithm: RS256)
• Verwenden Sie den X-SHA256-Checksum-Header, um den SHA256-Hashwert des Inhalts zu übermitteln ( X-SHA256-Checksum: e1d58ba0a1810d6dca5f086e6e36a9d81a8d4bb00378bdab30bdb205e7473f87)
• Verwenden Sie den X-Encryption-Algorithm-Header, um die Art der Inhaltsverschlüsselung mitzuteilen ( X-Encryption-Algorithm: A128CBC-HS256)

• Konsequent (vermeide Überraschungen, indem du vorhersehbar bist)
• Kohäsiv (listet nur Endpunkte mit funktionaler Abhängigkeit auf)
• Vollständig (verfügt über alle erforderlichen Endpunkte für seinen Zweck)
• Minimal (nicht mehr Endpunkte als notwendig, um vollständig zu sein, kein Featureismus)
• Einkapseln (Ausblenden von Implementierungsdetails)
• Selbsterklärend
• Dokumentiert (wenn Selbsterklärung nicht ausreicht)

• WSO2
• Apigee
• IBM
• SoftwareAG
• Maultier