Clever Geek Handbook

Como escrever uma API amigável - 10 práticas recomendadas

Eu sou um desenvolvedor e na maior parte da minha carreira tenho criado APIs para vários serviços. As diretrizes para este artigo foram compiladas com base nos problemas mais comuns ao projetar seu próprio serviço como uma equipe ou usar APIs de terceiros.





Provavelmente, você encontrou provedores de API terríveis. Trabalhar com eles, via de regra, está associado ao aumento da emocionalidade e da incompreensão. A maioria desses problemas pode ser evitada projetando a interface do aplicativo usando as dicas abaixo.





1. Não use verbos no URL *

* - se esta for uma das operações CRUD.





Os métodos de solicitação CRUD são responsáveis ​​pela ação com o recurso: POST - criar (criar), GET - obter (ler), PUT / PATH - atualizar (atualizar), DELETE - excluir (você entende). Ruim:





POST /users/{userId}/delete -  
POST /bookings/{bookingId}/update -

OK:





DELETE /users/{userId}
PUT /bookings/{bookingId}

2. Use verbos no URL

Ruim:





POST /users/{userId}/books/{bookId}/create -

OK:





POST /users/{userId}/books/{bookId}/attach
POST /users/{userId}/notifications/send -

3. Destacar novas entidades

Acima há um exemplo de como adicionar um livro a um usuário, talvez a lógica de seu aplicativo implique em uma lista de favoritos, então o caminho pode ser assim:





POST /wishlist/{userId}/{bookId}

4. Use um ID de recurso *

* - se sua estrutura de dados permitir.





Isso significa que se você tiver registros um-para-muitos, por exemplo,

reserva -> viajantes (reserva-> viajantes), será suficiente que você passe o ID do viajante na solicitação.





Ruim:





#   
GET /bookings/{bookingId}/travellers/{travellerId}

OK:





GET /bookings/travellers/{travellerId}

Também observo que /bookings/travellers/



é melhor do que apenas /travellers



se ater bem à hierarquia de dados em sua API.





5.

:





GET /user/{userId} -   
POST /ticket/{ticketId}/book -

:





GET /users/{userId}
POST /tickets/{ticketId}/book

6. HTTP-

- . . :





  • 400 Bad Request - , , .





  • 401 Unauthorized - .





  • 403 Forbidden - , .





  • 404 Not Found - .





  • 409 Conflict - , .





  • 500 Internal Server Error - .





  • 503 Service Unavailable - .





7.

. , - (quizzes passed_quizzes). , .





: /quizzes



/quizzes/passed



. quizzes



- (), passed



- ().





:





GET /passed-quizzes -   
GET /booked-tickets -   
POST /gold-users -

:





GET /tickets/booked
POST /users/gold

8.

API - . , , .





:





GET /book/{bookId}
{
    "name": "Harry Potter and the Philosopher's Stone",
    "genre": "fantasy",
    "status": 0, #   
    "error": false, 
    ...
}

:





GET /book/{bookId}
{
    "status": 0,
    "message": "ok",
    "data": {...}
}

3 . status



, message



- , , . , , . 409 status



message



.





9. json camelCase

9.1 Em parâmetros de consulta

ruins:





GET /users/{user-id}
GET /users/{user_id}
GET /users/{userid}

OK:





GET /users/{userId}
POST /ticket/{ticketId}/gold

9.2 No corpo da resposta ou solicitação recebida

Ruim:





{
    "ID": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
    "Name": "soccer3000",
    "provider_id": 1455,
    "Created_At": "25.05.2020"
}

OK:





{
    "id": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
    "Name": "soccer3000",
    "providerId": 1455,
    "createdAt": "25.05.2020"
}

10. Use Content-Type

Ruim:





GET /tickets.json
GET /tickets.xml

OK:





GET /tickets
//   
ontent-Type: application/json
// 
ontent-Type: application/xml

Conclusão

As recomendações listadas acima não são a lista completa de maneiras de tornar a API melhor. Para um estudo mais aprofundado, recomendo que você analise as especificações da API REST e a lista de códigos de status http (você ficará surpreso com quantos existem e quais situações eles abrangem).





E nos comentários, sugiro escrever sua própria recomendação para construir uma API REST que você considera importante.







More articles:


All Articles