Skip to main content

Rest API

  • Rest API

Interface uniforme​

As interações entre os componentes da Web – ou seja, seus clientes, servidores e intermediários

baseados em rede – dependem da uniformidade de suas interfaces. Se algum dos componentes se

desviar dos padrões estabelecidos, o sistema de comunicação da Web será interrompido.

O estilo arquitetônico REST é comumente aplicado ao design de APIs para serviços da Web modernos. Uma API da Web em conformidade com o estilo arquitetônico REST é uma API REST

Ter uma API REST torna um serviço web “RESTful”

Formato URI​

  • RFC : https://www.rfc-editor.org/rfc/rfc3986

  • Não devemos colocar “/” no final da URI

  • Hífen (-) deve ser usado para melhorar legibilidade

  • Sublinhados (_) não deve ser usados em URIs

  • Usar letras minúsculas de preferência

  • Não se deve usar a extensão do arquivo na URI

    • Para isso existe o cabecalho com o content-type

  • Nomes de função CRUD não devem ser usados em URIs

    • Os métodos de solicitações HTTP devem ser usados para indicar qual função CRUD é executada

    • DELETE /users/1234 - OK

      GET /deleteUser?id=1234 - ERRADO

      GET /deleteUser/1234 - ERRADO

      DELETE /deleteUser/1234 - ERRADO

      POST /users/1234/delete - ERRADO

Methods​

  • GET pode conter cabeçalhos, mas não corpo
  • HEAD retorna apenas os cabecalho da requisição sem o corpo. Ele é um “GET” sem o corpo
  • PUT deve inserir ou atualizar um recurso a um armazenamento
  • POST os clientes usam POST ao tentar criar um novo recurso em uma coleção
    • Os clientes usam o método POST para invocar os recursos do controlador orientado a função
    • o método POST não deve ser usado para obter, armazenar ou excluir recursos

Status code​

  • 200 - Exige corpo
  • 202 (“Aceito”) deve ser usado para indicar o início bem-sucedido de uma ação

assíncrona Uma resposta 202 indica que a solicitação do cliente será tratada de forma

assíncrona.

  • 204 (“Sem conteúdo”) deve ser usado quando o corpo da resposta estiver

intencionalmente vazio O código de status 204 geralmente é enviado em resposta a uma

solicitação PUT, POST ou DELETE , quando a API REST se recusa a enviar qualquer mensagem de

status ou representação no corpo da mensagem de resposta.

  • 301 (“Movido Permanentemente”) deve ser usado para realocar recursos O código de

status 301 indica que o modelo de recursos da API REST foi redesenhado significativamente e um

novo URI permanente foi atribuído ao recurso solicitado pelo cliente. A API REST deve especificar o novo URI no cabeçalho Location da resposta

  • 404 (“Not Found”) deve ser usado quando o URI de um cliente não pode ser mapeado para um recurso

Cabecalhos HTTP​

  • Content-type: Nomeia o tipo de dados encontrados no corpo de uma mensagem de solicitação ou resposta
  • Content-length: fornece o tamanho do corpo da entidade em bytes. É importante para o cliente se ele leu corretamente os valores enviados
  • Last-Modified: Deve ser usado apenas em respostas, o valor é um carimbo de data/hora que indica a última vez que algo acontecer para alterar o estado do recurso. Esse cabecalho sempre deve ser fornecido em resposta a solicitações GET (Esquisito pois teriamos que deixar a data salva no banco ou em cache)
  • Pontos interessantes sobre o método PUT e operações condicionais na página 53-54
  • Location: Define a URL do recurso recém criado
  • Date: Deve definir o horário do retorno da resposta
  • Se a resposta da API não deve ser usado para armazenar cache, devemos definir
    • Cache-Control: no-cache ou no-store
    • Pragma: no-cache
    • Expires: 0