Buenas prácticas: Nomenclatura API

Este es un extracto traducido de algunos de los 22 puntos de este artículo de Mohammad Faisal, al que recomiendo seguir, así como al canal BetterProgramming.

Link del artículo original: https://link.medium.com/urkTEwQzmib

Link de Mohammad Faisal: https://56faisal.medium.com/

Link de BetterProgramming: https://betterprogramming.pub/

Solo he obtenido los puntos relativos a nomenclatura, pero todos los demás son muy interesantes.

1. Usar kebab-case para las URLs. 

Mal

/systemOrders
/system_orders

Bien

/system-orders

2.Usar camelCase para los parámetros.

Mal

/system-orders/{order_id}
/system-orders/{OrderId}

Bien

/system-orders/{OrderId}

3. Usa plurales para apuntar a una colección.

Si quieres obtener todos los usuarios de un sistema:

Mal

GET /user
GET /User

Bien

GET /users

4. No utilices verbos en la URL

Mal

POST /updateuser/{userId}
GET /getusers

Bien

PUT /user/{userId}

5. Usa camelCase para propiedades JSON

Mal

{
user_name: "Mohammad Faisal"
user_id: "1"
}

Bien

{
userName: "Mohammad Faisal"
userId: "1"
}

6. No expongas tu arquitectura, como el nombre de tu tabla como un recurso.

Mal: product_order

Bien: product-orders

7. Usa ordinales simples como versión.

Usa el código de versión de forma simple, con versiones enteras lo mas a la izquierda  posible. Esto permitirá tener colecciones de endpoint y modificar enpoints a su derecha sin romper la funcionalidad de versiones anteriores.

http://api.domain.com/v1/shops/3/products

8. Incluye el número total de recursos en tu respuesta.

Mal

{
    users: [
     ...
    ]
}

Bien

{
    users: [
    ...
    ],
    total: 34
}

9. Usar métodos HTTP para funciones CRUD. 
Se relaciona con el 4.

GET: Obtiene una representación de un recurdo

POST: Crea un nuevo recurso y subrecursos

PUT: Actualiza recursos existentes

PATCH: Actualiza recursos existentes, pero solo actualiza los campos que fueron utilizados, dejando los demás como estaban.

DELETE: Borra un recurso