logo

Desenho de uma API REST

Blog do Rui API

Uma API REST tenta simplificar e criar um modelo uniforme de comunicação de dados entre os sitemas que utilizam HTTP.

Desta forma, uma vez que vamos usar HTTP então devemos utilizar tudo o que este protocolo já nos fornece. Por um lado estamos, em nome da simplificação, a adaptar a nossa API à tecnologia já existente, o HTTP. No caso do RPC é o contrário, os seja, o HTTP foi "adaptado", ou usado, de forma a permitir chamar um procedimento, tratando dos seus parametros e respetivos resultados de saída.

Anatomia de um pedido HTTP

Um pedido HTTP é contituído por:

  • Verbo - Acção a tomar: GET, POST, PUT, DELETE, OPTIONS, PATCH, ...
  • URL - localização do recurso sobre o qual queremos efetuar a ação
  • Parametros - Dados relativos ao pedido: podem ir na forma de Headers, URL parameters ou Body

uma vez tratado o servidor envia uma resposta constituída por:

  • Código do estado - um código númerico que indica como correu a operação
  • Parametros - Dados da resposta: podem ir na forma de Headers ou Body

ou seja, este protocolo já nos fornece uma estrutura que podemos utilizar numa API, para indicar o que queremos, onde, devidamente parameterizado, e recebendo uma resposta com o resultado e se necessárias outras informações.

Anatomia de um pedido REST

Uma vez que o HTTP já nos fornece uma estrutura, o REST vai reaproveitar essa estrutra de forma a manter a sinplicidade e reutilizar conhecimento já existente, tornando assim mais fácil a aprendizagem de novas API's.

Tendo em conta que o REST foi pensado para operações CRUD (Create Read Update Delete) sobre Entidades (recursos), este casamento entre REST e HTML é perfeitamente possível, senão vejamos a seguinte tabela de conversão:

CRUD HTML REST
CREATE  Livro  (titulo=Meu livro, autor=Rui, ...) POST /livro {"titulo":"Meu livro", "autor": "Rui",...}
READ  Livro GET /livro
UPDATE Livro(12)  preço=10 PUT /livro/12  {"preço": 10}
DELETE Livro(12) DELETE /livro/12

Podemos mapear o CRUD no HTML sem qualquer problema. E essa é a ideia principal do REST, reutilizar a estrutura do HTML para realizar as operações CRUD.

A estrutura de um pedido REST será então igual à estrutura de um pedido HTML, seguindo algumas convenções de mapeamento, que nos irão permitir decobrir/utilizar API's facilmente, e que iremos ver em detalhe de seguida.

Criar uma entidade em REST (CREATE)

Para criar uma entidade iremos fazer um POST para o URL com o nome da entidade, e no body enviamos os dados dessa entidade, normalmente no formato JSON. Na resposta obtemos o estado da operação e a entidade criada (ou a sua localização). Por exemplo, para criar um novo livro:

Pedido:

Verbo URL Parâmetros
POST /livros

body: {"titulo":"Meu livro", "autor": "Rui",...}

header: Content-Type: application/json

Resposta:

Codigo e Descrição Parâmetros
201 Created

body: {"id":21, "titulo":"Meu livro", "autor": "Rui",...}

header: Content-Type: application/json

OU MELHOR
201 Created

header: Content-Type: application/json

header: Location: /livros/21

Na resposta é comum enviar a entidade criada, já inclindo o identificado, no entanto, segundo o protocolo HTTP, citando https://tools.ietf.org/html/rfc7231#section-7.1.2:

"..The "Location" header field is used in some responses to refer to a specific resource in relation to the response. ... For 201 (Created) responses, the Location value refers to the primary resource created by the request"

assim sendo o mais correto será enviar no header location o link para o recurso criado. O código da resposta é "201 Created".

 

READ em REST

 

 

em desenvolvimento ...

Os Parametros num pedido REST

em desenvolvimento ...

 

 

 


Deixe o seu comentário