Repousante

Dec 16 2022

Quais são as seis restrições da API REST?
Cliente — Arquitetura do servidor — Esta regra garante a separação de interesses. O cliente gerencia as preocupações da interface do usuário enquanto o servidor gerencia as questões de persistência de dados. Em troca, obtemos um sistema altamente portátil onde uma vez que a API REST pode gerenciar diferentes clientes.
Stateless — Nenhum dado do cliente pode ser armazenado no servidor entre as solicitações. Caso o estado do cliente seja relevante para as requisições, ele deve ser enviado junto com as requisições. Se o servidor precisar salvar as sessões do cliente, elas devem ser salvas em um banco de dados por um determinado período.
Cacheability — Todas as respostas devem ser marcadas como armazenáveis em cache ou não armazenáveis em cache. Se a resposta puder ser alterada constantemente, não devemos armazená-los em cache. A capacidade de cache é importante para o desempenho da API REST.
Sistema em Camadas — O cliente não pode saber/não deve se importar se está conectado diretamente ao servidor original ou intermediário ao longo do caminho. Isso significa que o REST permite que você tenha uma arquitetura de sistema em camadas e a solicitação pode ser enviada por diferentes camadas. Isso ajuda na segurança e escalabilidade (CDN, servidor de autorização).
Código sob demanda — a API REST pode transferir arquivos JavaScript executáveis e componentes compilados para o cliente quando necessário.
Interface Uniforme — Como o nome indica, deve haver uma interface para os recursos que são expostos aos clientes da API. Um recurso no servidor deve ter apenas um URI lógico para recuperar ou manipular o recurso.

baseado na arquitetura cliente-servidor
e deseja atender diferentes clientes por meio do protocolo HTTP
e deseja usar as restrições REST descritas acima

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

Use OAuth2 para proteger sua API.
Use um token Bearer de expiração automática para autenticação ( Authorisation: Bearer f0ca4227-64c4-44e1-89e6-b27c62ac2eb6).
Requer HTTPS.
Considere o uso de JSON Web Tokens .
Imponha o uso dos cabeçalhos Content-Type e Accept-Type, mesmo se você usar JSON como padrão para solicitações e respostas.

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

As respostas contêm cabeçalho:X-Frame-Options: deny

Nível 0: Defina um URI e todas as operações são solicitações POST para este URI.
Nível 1: Crie URIs separados para recursos individuais.
Nível 2: Use métodos HTTP para definir operações em recursos.
Nível 3: Use hipermídia (HATEOAS, descrito abaixo).

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

Para um método POST, o URI representa um recurso pai da nova entidade, como uma coleção. Por exemplo, para criar um novo filme, o URI pode ser /api/movies. O servidor cria a entidade e atribui a ela um novo URI, como /api/movies/6812360. Esse URI é retornado no cabeçalho Location da resposta. Cada vez que o cliente enviar uma solicitação, o servidor criará uma nova entidade com um novo URI.
Para um método PUT, o URI identifica a entidade. Se já existir uma entidade com esse URI, o servidor atualiza a entidade existente com a versão da solicitação.

Cache-Control — O número máximo de segundos (ttl) que uma resposta pode ser armazenada em cache. ( Cache-Control: public, 360ou Cache-Control: no-store)
O cache forte minimiza o número de solicitações que um servidor recebe
Considere o cache fraco por meio do ETagcabeçalho de resposta
ETag — Use um hash SHA1 para a versão de um recurso. Certifique-se de incluir o tipo de mídia no valor de hash, porque isso cria uma representação diferente. ( ETag: "2dbc2fd2358e1ea1b7a6bc08ea647b9a337ac92d"). O cliente precisa enviar um cabeçalho If-None-Match para que esse mecanismo funcione.
O cache fraco minimiza o trabalho que um servidor precisa fazer (mas não o número de solicitações que ele recebe)
Habilite o cache baseado em cabeçalho em todos os proxies e clientes (por exemplo, NGINX, Apache, APIM) para aumentar a velocidade e a robustez
Nenhum dado que comprometa a privacidade ou a segurança nas URLs

Implemente a criptografia de conteúdo nos endpoints mais distantes (no servidor REST, não nos proxies ou APIM)
Quando a assinatura de conteúdo é usada, isso é feito depois que o conteúdo é (opcionalmente) criptografado.
Use o cabeçalho X-Signing-Algorithm para comunicar o tipo de assinatura de conteúdo ( X-Signing-Algorithm: RS256)
Use o cabeçalho X-SHA256-Checksum para comunicar o valor de hash SHA256 do conteúdo ( X-SHA256-Checksum: e1d58ba0a1810d6dca5f086e6e36a9d81a8d4bb00378bdab30bdb205e7473f87)
Use o cabeçalho X-Encryption-Algorithm para comunicar o tipo de criptografia de conteúdo ( X-Encryption-Algorithm: A128CBC-HS256)