5.3 KiB
title | localeTitle |
---|---|
Rest API Design | Design da API de descanso |
História
RESTO significa Re protocolo T ransferência S tate apresentação. Roy Fielding definiu REST em sua dissertação de doutorado no ano 2000.
O que é isso?
O REST foi desenvolvido para fornecer uma interface uniforme para
- Identificando recursos
- Manipulação de recursos
- Mensagens descritivas
- Usando a hipermídia como o mecanismo do estado do aplicativo (HATEOS)
Melhores práticas
- #### Noções básicas
| Método | http://api.co/v2/cars | http://api.co/v2/cars/1234 |
| --- | --- | --- | | GET | Listar todos os carros | Recuperar um carro individual | | POST | Crie um carro novo | Erro | | PÔR | Substituir coleções de carros por uma nova | Substitua o carro com id 1234 | | DELETE | Apagar todos os carros | Apagar carro com id 1234 |
Observe enquanto as operações PUT, cliente ou servidor, podem gerar id's
-
Os substantivos são bons Os verbos são ruins
-
Use substantivos para referenciar recursos como
cars
,fruits
etc. -
Use verbos para declarações de ação
convertMilesToKms
,getNutritionalValues
-
Singular ou plural?
Use a gramática correta para declaração
Evitar
/person/145
Prefiro
/people/154
Suponho retornar a 154ª pessoa da lista de pessoas -
Use revestimento
Use qualquer um dos padrões abaixo e seja consistente!
| Estilos de maiúsculas | Exemplo | | ------------- | ------------- | | UpperCamelCase |
http://api.fintech.cp/DailyTransactions/Today
| | lowerCamelCase |http://api.fintech.cp/dailyTransactions/today
|
| snake_case |http://api.fintech.cp/daily_transactions/today
| -
Relacionamentos e Recursos
-
Os recursos podem ter relacionamentos
one-to-many
,many-to-many
,many-to-one
etc. O mapeamento correto deles é crucial. -
Mapeamento de um para muitos
Por exemplo,
Tickets/145/messages/4
sugere relação um-para-muitos entretickets
emessages
. Significado1
ticket temN
mensagens. A mensagem não é um recurso autônomo. Você não pode ter/messages/4
. -
Muitos para muitos mapeamento
Por exemplo,
/usergroups/345/users/56
sugere selecionar o 345º grupo de usuários e obter o usuário com o ID 56. Entretanto, um usuário pode estar em váriosusergroups
isto é,/usergroups/209/users/56
também é válido. Nesse caso, para separar osusers
recurso depedente em um ponto de extremidade separado como/users/56
e fornecer a vinculação de recursos em/usergroups/209/users/56
-
Parâmetros da API
-
CAMINHO : necessário para acessar o recurso Por exemplo,
/cars
/fruits
-
Parâmetros de consulta : opcional filtrar a lista Por exemplo
/cars?type=SUV&year=2010
-
Corpo : Lógica específica do recurso. Consulta de pesquisa avançada. Às vezes, pode ter tanto consulta quanto corpo.
-
Cabeçalho : deve conter dados globais ou de plataforma ampla. Por exemplo, parâmetros de chave de API, chaves criptografadas para autenticação, informações de tipo de dispositivo, por exemplo, móvel ou desktop ou endpoint, tipo de dados do dispositivo, por exemplo, xml ou json. Use o cabeçalho para comunicar esses parâmetros
-
Códigos de Status HTTP
Use códigos de status corretos
| Códigos | Significado | | ------------- |: -------------: | | 1xx | Solicitação recebida e entendida. | | 2xx | Ação solicitada pelo cliente foi recebida, entendida e solicitada. | | 3xx | O cliente deve tomar medidas adicionais para concluir a solicitação. A maioria desses códigos de status é usada no redirecionamento de URL. | | 4xx | Destinado a situações em que parece que o erro foi causado pelo cliente. | | 5xx | O servidor não conseguiu atender a uma solicitação. |
Pouco mais em 2xx !
-
201 Recurso Criado. POST
/cars
devem retornar o HTTP 201 criado com o cabeçalho delocation
informando como acessar o recurso Por exemplo,location
:api.com/cars/124
no cabeçalho -
202 - Aceito
Use isso se a tarefa for grande para ser executada. Diga ao cliente, aceitou o pedido e processará / processará Nenhuma carga é retornada
-
204 - Nenhum conteúdo
Usada quando excluídos
DELETE cars/124
Não retorna conteúdo. Mas também pode retornar200 OK
se a API pretende enviar o recurso excluído para processamento adicional.Os perigosos recursos 5xx !
-
500 Erro interno do servidor
-
504 Tempo limite do gateway. O servidor não recebeu resposta em tempo hábil
Menos conhecido 4xx sugere que você está passando o parâmetro errado. Também pode passar informações erradas. Por exemplo
DELETE /cars/MH09234
retorna
4xx
ou mensagemExpecting int car id /car/id got string car/MH09234
Leitura adicional
Como criar ótimas APIs - Analisar o dia do desenvolvedor 2013
O interminável debate de design da API REST por Guillaume Laforge