Soy desarrollador y durante la mayor parte de mi carrera he estado creando API para varios servicios. Las pautas para este artículo se han compilado en función de los problemas más comunes al diseñar su propio servicio en equipo o al utilizar API de terceros.
Lo más probable es que te hayas encontrado con proveedores de API terribles. Trabajar con ellos, por regla general, se asocia con una mayor emocionalidad y malentendidos. La mayoría de estos problemas se pueden evitar diseñando la interfaz de la aplicación con los consejos que se muestran a continuación.
1. No uses verbos en la URL *
* - si esta es una de las operaciones CRUD.
Los métodos de solicitud CRUD son responsables de la acción con el recurso: POST - crear (crear), GET - obtener (leer), PUT / PATH - actualizar (actualizar), DELETE - eliminar (usted comprende). Malo:
POST /users/{userId}/delete -
POST /bookings/{bookingId}/update -
Okey:
DELETE /users/{userId}
PUT /bookings/{bookingId}
2. Usa verbos en la URL.
Malo:
POST /users/{userId}/books/{bookId}/create -
Okey:
POST /users/{userId}/books/{bookId}/attach
POST /users/{userId}/notifications/send -
3. Destacar nuevas entidades
Arriba hay un ejemplo de cómo agregar un libro a un usuario, tal vez la lógica de su aplicación implique una lista de favoritos, entonces la ruta puede ser así:
POST /wishlist/{userId}/{bookId}
4. Utilice un ID de recurso *
* - si su estructura de datos lo permite.
Esto significa que si tiene registros de uno a varios, por ejemplo,
reserva -> viajeros (reserva-> viajeros), será suficiente con pasar el ID de viajero en la solicitud.
Malo:
#
GET /bookings/{bookingId}/travellers/{travellerId}
Okey:
GET /bookings/travellers/{travellerId}
También observo que /bookings/travellers/
es mejor que limitarse a /travellers
ceñirse bien a la jerarquía de datos en su 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 En los parámetros de consulta
Malo:
GET /users/{user-id}
GET /users/{user_id}
GET /users/{userid}
Okey:
GET /users/{userId}
POST /ticket/{ticketId}/gold
9.2 En el cuerpo de la respuesta o solicitud recibida
Malo:
{
"ID": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"provider_id": 1455,
"Created_At": "25.05.2020"
}
Okey:
{
"id": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"providerId": 1455,
"createdAt": "25.05.2020"
}
10. Utilice el tipo de contenido
Malo:
GET /tickets.json
GET /tickets.xml
Okey:
GET /tickets
//
ontent-Type: application/json
//
ontent-Type: application/xml
Conclusión
Las recomendaciones enumeradas anteriormente no son la lista completa de formas de mejorar la API. Para un estudio más detallado, le recomiendo que analice las especificaciones de la API REST y la lista de códigos de estado http (se sorprenderá de cuántos hay y qué situaciones cubren).
Y en los comentarios, sugiero escribir su propia recomendación para construir una API REST que considere importante.