practices - restful api url convention

Acciones de REST y consideraciones de diseño de URL API

Question

Estoy construyendo un sistema de gestión de inventario y estoy ocupado diseñando (pensando) en la API y en la implementación de REST.

Tengo los siguientes recursos y en el recurso puede realizar muchas acciones / operaciones. Cada operación modificará el recurso y, en algunos casos, creará un nuevo recurso y también creará historial o transacciones.

Estoy buscando información de expertos sobre la usabilidad y aceptabilidad en cuanto a diseño de URL y recursos. Los ejemplos de gotchas y del mundo real, cualquier opinión o crítica bienvenida.

Mi preocupación es que toda la aplicación podría desarrollarse alrededor de este gran recurso. Mi backend será C # y el framework de la plataforma de servicios y para frontend usaré HTML y AngularJS. No es que haga la diferencia.

Escenario 1. La operación típica será:

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /inventory/{id}/pick
PUT  /inventory/{id}/receive
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /inventory/{id}/transfer
POST /inventory/{id}/return
POST /inventory/{id}/adjustment


{
  "userID": "",       //who is doing the actions (all)
  "tolocationID": "", //new location for inventory (move/takeon/pick/receive/transfer/return)
  "qty": "",          //qty (pick/receive/takeon/transfer/return)
  "comment": "",      //optional for transaction (all)
  "serial": "",       //(takeon/receive)
  "batch": "",        //(takeon/receive)
  "expirydate": "",   //(takeon/receive)
  "itemCode": "",     //(takeon/receive)
  "documentID": "",   //(pick/receive/return/transfer)
  "reference" :"",    //(all)
  "UOM" :"",          //(all)
  "reference" :"",    //(all)
}

¿Es esto aceptable con respecto a los estándares? El otro enfoque podría ser.

Escenario 2.

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /document/{id}/pick     //**document**
PUT  /document/{id}/receive  //**document**
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /document/{id}/transfer  //**document**
POST /document/{id}/return    //**document**
POST /inventory/{id}/adjustment

y luego para cambiar los recursos.

Escenario 3. en mi opinión incorrecto

POST /transaction/move/{...}
POST /transaction/scrap/{...}
PUT  /transaction/takeon/{...}
POST /transaction/pick/{...}  
PUT  /transaction/receive/{...} 
POST /transaction/hold/{...}
POST /transaction/release/{...}
POST /transaction/transfer/{...}  
POST /transaction/return/{...}
POST /transaction/adjustment/{...}

¿Algún comentario bienvenido, sin buscar respuesta pero más consejos sobre consideraciones de diseño?

¡Gracias por tomarse el tiempo de leer esta entrada!

Answer 1

Tengo los siguientes recursos y en el recurso puede realizar muchas acciones / operaciones. Cada operación modificará el recurso y, en algunos casos, creará un nuevo recurso y también creará historial o transacciones.

Fundamental para el esquema arquitectónico REST es la idea de utilizar los verbos HTTP como el único verbo y sin incluir los verbos en sus URL. En su lugar, consideraría volver a trabajar su sistema para eliminar los verbos. Es difícil sugerir un diseño sin saber realmente lo que significan los verbos, pero tal vez algo más cercano a:

GET /inventory/{id}
PUT /inventory/{id} -- update with new location 
PUT /inventory/{id} -- update with new status (scrapped)

etc. Ese es un enfoque más RESTful. Muchas de estas acciones parecen simplemente PUTs que actualizan múltiples propiedades del recurso, como ubicación, cantidad, campo de comentarios, etc. ¿Y quizás la scrap es DELETE? Difícil de decir.

Otra opción sería usar POST, donde el cuerpo incluye las instrucciones sobre cómo operar el artículo del inventario:

POST /inventory-transactions/{id}
{
    "action": "takeon",
    "newLocationId": 12345,
    ...
}

Esto le proporciona una gran cantidad de rastreabilidad, ya que cada operación ahora se puede rastrear como un recurso. El lado negativo es una gran complejidad alrededor del punto final.

También puede dividir algunas de las operaciones "verbales" en recursos:

POST /returned-inventory
{
    "inventoryId": 12345,
    "documentId": 67890,
    "comment": "Busted up",
    ...
}

Esto le permite ver fácilmente los artículos del inventario por su estado, lo que puede o no ser útil. Podría, por ejemplo, llamar GET /returned-inventory?documentId=67890 para recuperar todos los elementos devueltos del mismo documento.

Esperemos que haya algo de reflexión allí. Realmente no va a ser posible que alguien le diga lo "correcto" sin conocer los requisitos de su negocio con mayor detalle.

Answer 2

"Restful Objects", que define una API RESTful, establece que las acciones son válidas.

Las acciones disponibles pueden descubrirse, habilitarse / deshabilitarse, y pueden dar una respuesta de "razón desactivada".

Las acciones se ''invocan'' usando GET (consulta), PUT (idempotente) o POST (no idempotente)

Especificación de objeto relajante (página C-125)