Texto das anotações sobre o que que estudei e vi no trabalho, continuação da série sobre API RESTful.
RESTful
O que é API RESTful?
Quando um serviço REST é executado na web sobre HTTP para nos dar acesso a um recurso da web, o chamamos de API RESTful.
Se enviarmos uma solicitação por meio de HTTP para um serviço REST que atenda às seis restrições (mencionei elas na parte 1), esse serviço será uma API RESTful.
Nem todas as APIs REST usam o protocolo HTTP mas as APIs RESTful usam.
O que uma API REST faz?
O trabalho da API REST é receber solicitações, processar dados e enviar respostas.
Ela fornece uma interface para que um conjunto de dados seja consumido por qualquer cliente que siga as regras (o próprio site, aplicativos ou dispositivo IoT).
Qualquer cliente pode acessar qualquer API?
APIs REST tem limites (e se ainda não tem, precisam se adequar imediatamente, por segurança) sobre quais recursos podem ser acessados, que clientes pode acessar o que e quantidade de solicitações que podem ser feitas em um determinado período de tempo.
Como posso testar se um recurso de uma API REST funciona, ver seu retorno e etc?
Você vai precisar de ferramentas na sua máquina como o Insomnia ou Postman. Dependendo da IDE que você utiliza, pode encontrar algum client para usar nela mesma. Se assim como eu, você usa VS Code, é possível baixar uma extensão de REST client.
Neste site tem uma lista dos 20 melhores clients, entre gratuitos e pagos.
Request
O que é uma request?
Uma solicitação REST tem duas partes: um método e um URI.
Método - GET, POST, PUT, DELETE, OPTIONS ou outro verbo.
URI - aponta para o recurso que desejamos interagir.
Também podemos enviar metadados no cabeçalho da solicitação.
Além disso, a solicitação pode ficar mais complexa e também precisaremos enviar os dados que queremos modificar (caso de solicitações com métodos POST, PATCH e PUT, por exemplo, que também enviam um body e headers) e o tipo do conteúdo (JSON, por exemplo).
Recurso
Qualquer informação que possa ser nomeada pode ser um recurso(1).
Um recurso é um mapeamento conceitual para um conjunto de entidades. Recursos podem retornar listas de objetos ou um único objeto.
Por exemplo, “clientes” é um recurso de coleção e “cliente” é um recurso singleton (em um domínio bancário). Podemos identificar o recurso de coleta de “clientes” usando o URN “/clientes”. Podemos identificar um único recurso de “cliente” usando o URN “/customers /{customerId}”.(1)
O recurso é qualquer dado que esteja no local para o qual estamos apontando.
Representação
Representação é a representação literal dos dados que obtemos quando acessamos esse recurso.
No retorno da solicitação não acessamos os dados reais, acessamos uma representação destes. Por isso, um recurso REST pode fornecer os mesmos dados a vários clientes, ao mesmo tempo, assim como pode fornecer diferentes variantes desses dados a clientes diferentes mediante solicitação.
Referências
(1)Architectural Styles and
the Design of Network-based Software Architectures - Roy Fielding, 2000
(2)REST API Design Resource Modeling - Prakash Subramaniam, 2014
Outras referências:
Top comments (4)
Que artigo incrível ♥️
obrigada! Escrever tem me ajudado a fixar melhor na cabeça estas coisas "simples" que eu vejo todo dia mas que, na hora de explicar, sumia tudo.
Parabéns e obrigado
fico feliz que foi útil! Eu que agradeço o feedback :D