Riposo

Dec 16 2022

Quali sono i sei vincoli dell'API REST?
Client — Server Architecture — Questa regola assicura la separazione delle preoccupazioni. Il client gestisce i problemi dell'interfaccia utente mentre il server gestisce i problemi di persistenza dei dati. In cambio, otteniamo un sistema altamente portabile in cui una volta l'API REST può gestire diversi client.
Statelessness : nessun dato client può essere memorizzato sul server tra le richieste. Se lo stato del client è rilevante per le richieste, deve essere inviato insieme alle richieste. Se il server deve salvare le sessioni client, dovrebbe essere salvato in un DB per un determinato periodo di tempo.
Cacheability : tutte le risposte devono essere contrassegnate come memorizzabili nella cache o non memorizzabili nella cache. Se la risposta può essere modificata costantemente, non dovremmo memorizzarli nella cache. La memorizzazione nella cache è importante per le prestazioni dell'API REST.
Sistema a più livelli : il cliente non può sapere/non dovrebbe preoccuparsi se si è connesso direttamente al server originale o all'intermediario lungo il percorso. Significa che REST ti consente di avere un'architettura di sistema a più livelli e la richiesta può essere inviata attraverso diversi livelli. Questo aiuta con sicurezza e scalabilità (CDN, server di autorizzazione).
Codice su richiesta : l'API REST può trasferire file JavaScript eseguibili e componenti compilati al client quando necessario.
Interfaccia uniforme : come suggerisce il nome, dovrebbe esserci un'interfaccia per le risorse esposte ai client API. Una risorsa nel server dovrebbe avere un solo URI logico per recuperare o manipolare la risorsa.

basata su architettura client-server
e desidera servire diversi client tramite il protocollo HTTP
e desidera utilizzare i vincoli REST descritti sopra

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

Usa OAuth2 per proteggere la tua API.
Utilizza un token Bearer con scadenza automatica per l'autenticazione ( Authorisation: Bearer f0ca4227-64c4-44e1-89e6-b27c62ac2eb6).
Richiedi HTTPS.
Prendi in considerazione l'utilizzo di JSON Web Token .
Imponi l'uso delle intestazioni Content-Type e Accept-Type anche se utilizzi JSON come impostazione predefinita sia per le richieste che per le risposte.

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

Le risposte contengono l'intestazione:X-Frame-Options: deny

Livello 0: definisci un URI e tutte le operazioni sono richieste POST a questo URI.
Livello 1: crea URI separati per le singole risorse.
Livello 2: utilizzare i metodi HTTP per definire le operazioni sulle risorse.
Livello 3: Usa l'ipermedia (HATEOAS, descritto di seguito).

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

Per un metodo POST, l'URI rappresenta una risorsa padre della nuova entità, ad esempio una raccolta. Ad esempio, per creare un nuovo film, l'URI potrebbe essere /api/movies. Il server crea l'entità e le assegna un nuovo URI, ad esempio /api/movies/6812360. Questo URI viene restituito nell'intestazione Location della risposta. Ogni volta che il client invia una richiesta, il server creerà una nuova entità con un nuovo URI.
Per un metodo PUT, l'URI identifica l'entità. Se esiste già un'entità con quell'URI, il server aggiorna l'entità esistente con la versione nella richiesta.

Cache-Control : il numero massimo di secondi (ttl) in cui una risposta può essere memorizzata nella cache. ( Cache-Control: public, 360o Cache-Control: no-store)
La memorizzazione nella cache avanzata riduce al minimo il numero di richieste ricevute da un server
Prendi in considerazione la memorizzazione nella cache debole attraverso l' ETagintestazione della risposta
ETag : utilizza un hash SHA1 per la versione di una risorsa. Assicurati di includere il tipo di supporto nel valore hash, perché ciò crea una rappresentazione diversa. ( ETag: "2dbc2fd2358e1ea1b7a6bc08ea647b9a337ac92d"). Il client deve inviare un'intestazione If-None-Match affinché questo meccanismo funzioni.
La cache debole riduce al minimo il lavoro che un server deve svolgere (ma non il numero di richieste che riceve)
Abilita la memorizzazione nella cache basata su intestazione su tutti i proxy e i client (ad es. NGINX, Apache, APIM) per aumentare la velocità e la robustezza
Nessun dato che compromette la privacy o la sicurezza negli URL

Implementa la crittografia dei contenuti sugli endpoint più lontani (nel server REST, non nei proxy o nell'APIM)
Quando viene utilizzata la firma del contenuto, questa operazione viene eseguita dopo che il contenuto è (facoltativamente) crittografato.
Utilizza l'intestazione X-Signing-Algorithm per comunicare il tipo di firma del contenuto ( X-Signing-Algorithm: RS256)
Utilizzare l'intestazione X-SHA256-Checksum per comunicare il valore hash SHA256 del contenuto ( X-SHA256-Checksum: e1d58ba0a1810d6dca5f086e6e36a9d81a8d4bb00378bdab30bdb205e7473f87)
Utilizza l'intestazione X-Encryption-Algorithm per comunicare il tipo di crittografia dei contenuti ( X-Encryption-Algorithm: A128CBC-HS256)