¿Cómo crear URL REST sin verbos?

StackOverflow https://stackoverflow.com/questions/1619152

  •  06-07-2019
  •  | 
  •  

Pregunta

Estoy luchando por determinar cómo diseñar URL relajantes. Estoy totalmente de acuerdo con el enfoque tranquilo de usar URL con sustantivos y no verbos, no entiendo cómo hacer esto.

Estamos creando un servicio para implementar una calculadora financiera. La calculadora toma varios parámetros que cargaremos a través de un archivo CSV. Los casos de uso implicarían:

  1. Cargar nuevos parámetros
  2. Obtenga los últimos parámetros
  3. Obtener parámetros para una fecha comercial determinada
  4. Activar un conjunto de parámetros
  5. Validar un conjunto de parámetros

Creo que el enfoque tranquilo sería tener las siguientes URL de tipo: 

/parameters
/parameters/12-23-2009

Podrías lograr los primeros tres casos de uso con:

  1. POST donde incluye el archivo de parámetros en la solicitud de publicación
  2. OBTENER la primera URL
  3. OBTENER la segunda URL

Pero, ¿cómo haces el cuarto y quinto caso de uso sin un verbo? ¿No necesitaría URL como: 

/parameters/ID/activate
/parameters/ID/validate

??

¿Fue útil?

Solución

Quizás algo como: 

PUT /parameters/activation HTTP/1.1
Content-Type: application/json; encoding=UTF-8
Content-Length: 18

{ "active": true }

Otros consejos

Principios generales para un buen diseño de URI:

  • No use los parámetros de consulta para cambiar el estado
  • No use rutas mixtas si puede evitarlo; en minúsculas es mejor
  • No use extensiones específicas de implementación en sus URI (.php, .py, .pl, etc.)
  • No caiga en RPC con sus URI
  • Haz limita tu espacio URI tanto como sea posible
  • Haz mantener cortos los segmentos de ruta
  • Do prefiera / resource o / resource / ; cree 301 redirecciones a partir de la que no usa
  • Do usa los parámetros de consulta para la subselección de un recurso; es decir, paginación, consultas de búsqueda
  • Haz mueve cosas fuera del URI que debería estar en un encabezado HTTP o un cuerpo

(Nota: no dije "diseño de URI RESTful"; los URI son esencialmente opacos en REST.)

Principios generales para la elección del método HTTP:

  • No nunca use GET para cambiar el estado; esta es una excelente manera de que Googlebot arruine tu día
  • No use PUT a menos que esté actualizando un recurso completo
  • No use PUT a menos que también pueda realizar legítimamente un GET en el mismo URI
  • No use POST para recuperar información que sea de larga duración o que sea razonable almacenar en caché
  • No realice una operación que no sea idempotent con PONER
  • Haz utiliza GET tanto como sea posible
  • Haga use POST en lugar de PONER en caso de duda
  • Haz utiliza POST siempre que tengas que hacer algo que parezca RPC
  • Haga use PUT para clases de recursos que sean más grandes o jerárquicos
  • Do use DELETE en lugar de POST para eliminar recursos
  • Haz usa GET para cosas como cálculos, a menos que tu entrada sea grande, en cuyo caso usa POST

Principios generales del diseño de servicios web con HTTP:

  • No ponga metadatos en el cuerpo de una respuesta que debería estar en un encabezado
  • No coloque los metadatos en un recurso separado, a menos que incluirlos generaría una sobrecarga significativa
  • Haz utiliza el código de estado apropiado
    • 201 Created después de crear un recurso; el recurso debe existir en el momento en que se envía la respuesta
    • 202 Accepted después de realizar una operación con éxito o crear un recurso de forma asíncrona
    • 400 Bad Request cuando alguien realiza una operación con datos que son claramente falsos; para su aplicación esto podría ser un error de validación; en general, reserva 500 para excepciones no capturadas
    • 401 No autorizado cuando alguien accede a su API sin proporcionar el encabezado necesario de Autorización o cuando las credenciales de Autorización no son válidas; no utilice este código de respuesta si no espera las credenciales a través de un encabezado Autorización .
    • 403 Forbidden cuando alguien accede a su API de una manera que podría ser malintencionada o si no está autorizada
    • 405 Método no permitido cuando alguien usa POST cuando debería haber usado PUT, etc.
    • 413 Solicitud de entidad demasiado grande cuando alguien intenta enviarle un archivo inaceptablemente grande
    • 418 Soy una tetera al intentar Prepara café con una tetera
  • Haz utiliza encabezados de almacenamiento en caché siempre que puedas
      Los encabezados de
    • ETag son buenos cuando puede reducir fácilmente un recurso a un valor de hash
    • Last-Modified debería indicarle que mantener una marca de tiempo de cuando se actualizan los recursos es una buena idea
    • Cache-Control y Expires deben tener valores razonables
  • Haga todo lo que pueda para honrar los encabezados de almacenamiento en caché en una solicitud ( Si-Ninguno-Modificado , If-Modified-Since )
  • Haz usa redirecciones cuando tengan sentido, pero estas deberían ser raras para un servicio web

Con respecto a su pregunta específica, POST debe utilizarse para los números 4 y 5. Estas operaciones se encuentran bajo el " RPC-like " directriz anterior. Para el # 5, recuerde que POST no necesariamente tiene que usar Content-Type: application / x-www-form-urlencoded . Esto podría ser fácilmente una carga útil JSON o CSV.

Cuando parezca que necesitas un nuevo verbo, piensa en convertir ese verbo en un nombre. Por ejemplo, convierta 'activar' en 'activación' y 'validar' en 'validación'.

Pero solo por lo que ha escrito, diría que su aplicación tiene problemas mucho mayores.

Cada vez que se propone un recurso llamado 'parámetro', debe enviar banderas rojas en la mente de cada miembro del equipo del proyecto. 'parámetro' puede aplicarse literalmente a cualquier recurso; no es lo suficientemente específico.

¿Qué representa exactamente un 'parámetro'? Probablemente una serie de cosas diferentes, cada una de las cuales debería tener un recurso separado dedicado a ella.

Otra forma de llegar a esto: cuando discute su aplicación con los usuarios finales (aquellos que presumiblemente saben poco sobre programación), ¿cuáles son las palabras que ellos mismos usan repetidamente?

Esas son las palabras con las que debes diseñar tu aplicación.

Si aún no ha realizado esta conversión con posibles usuarios, detenga todo ahora y no escriba otra línea de código hasta que lo haga. Solo entonces su equipo tendrá una idea de lo que se debe construir.

No sé nada sobre software financiero, pero si tuviera que adivinar, diría que algunos de los recursos pueden ir por nombres como "Informe", "Pago", "Transferencia" y "Moneda" ;.

Hay una serie de buenos libros en esta parte del proceso de diseño del software. Dos que puedo recomendar son Diseño controlado por dominio y Patrones de análisis .

El diseño de sus direcciones URL no tiene nada que ver con si su aplicación es REST o no. la frase " RESTful URLS " Por lo tanto, es una tontería.

Creo que deberías leer un poco más sobre lo que realmente es REST. REST trata la URL como opaca, y como tal no sabe lo que hay en ella, ya sea que haya verbos o sustantivos o lo que sea. Es posible que aún desee diseñar su URLS, pero eso es sobre la interfaz de usuario, no REST.

Dicho esto, lleguemos a tu pregunta: los dos últimos casos no son REST completos y no encajan en ningún tipo de esquema reparador. Esos son lo que podríamos llamar RPC. Si es serio acerca de REST, tendrá que replantearse cómo funciona su aplicación desde cero. O eso, o abandone REST y simplemente haga su aplicación como una aplicación RPC.

Hrmmm tal vez no.

La idea aquí es que tienes que tratar todo como un recurso, por lo que una vez que un conjunto de parámetros tiene una URL a la que puedes referirte, simplemente agregas

obtener [parametersurl] / validationresults

publicar [paramatersurl]

cuerpo: {comando: " activar "}

pero nuevamente, esa cosa activada es RPC, no REST.

Los requisitos de activación y validación son situaciones en las que intenta cambiar el estado de un recurso. No es diferente que hacer un pedido "completado", o alguna otra solicitud "enviada". Existen numerosas formas de modelar este tipo de cambio de estado, pero una que me parece que a menudo funciona es crear recursos de colección para recursos del mismo estado y luego mover el recurso entre las colecciones para afectar al estado.

por ejemplo Crea algunos recursos como, 

/ActiveParameters
/ValidatedParameters

Si desea activar un conjunto de parámetros, agréguelo a la colección ActiveParameters. Puede pasar el conjunto de parámetros como un cuerpo de entidad, o puede pasar una url como parámetro de consulta, de la siguiente manera: 

POST /ActiveParameters?parameter=/Parameters/{Id}

Lo mismo se puede hacer con / ValidatedParameters. Si los parámetros no son válidos, el servidor puede devolver " Solicitud incorrecta " a la solicitud para agregar los parámetros a la colección de parámetros validados.

Sugeriría los siguientes recursos y métodos Meta.

Active los parámetros y / o valídelos: 

> PUT /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Content-Type: application/json
> Connection: close
>
> {'active': true, 'require-valid': true}
>
< HTTP/1.1 200 OK
< Connection: close
<

Compruebe si los parámetros son activos y válidos: 

> GET /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Connection: close
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Connection: close
<
< {
<     'active': true,
<     'require-valid': true,
<     'valid': {'status': false, 'reason': '...'}
< }
<

En un entorno REST, cada URL es un recurso único. ¿Cuáles son tus recursos? Una calculadora financiera realmente no tiene ningún recurso obvio. Debe profundizar en lo que llama parámetros y extraer los recursos. Por ejemplo, un calendario de amortización para un préstamo podría ser un recurso. La URL del calendario puede incluir fecha de inicio, plazo (en meses o años), período (cuando el interés está compuesto), tasa de interés y principio inicial. Con todos esos valores tienes un calendario de pagos específico: 

http://example.com/amort_cal/2009-10-20/30yrsfixed/monthly/5.00/200000

Ahora, no sé lo que está calculando, pero su concepto de una lista de parámetros no suena REST. Como dijo alguien más, sus requisitos anteriores suenan más XMLRPC. Si usted está tratando de REST necesita sustantivos. Los cálculos no son sustantivos, son verbos que actúan sobre sustantivos. Necesitas darle la vuelta para sacar los sustantivos de tus cálculos.

Editar: De hecho, el URI habría evitado que las solicitudes de GET permanezcan en idempotente.

Sin embargo, para la validación, el uso de códigos de estado HTTP para notificar la validez de una solicitud (para crear una nueva o modificar un 'parámetro' existente) se ajustaría a un modelo Restful.

Informe con un código de estado 400 Bad Request si los datos enviados son / no son válidos y la solicitud debe modificarse antes de volver a enviarla ( HTTP / 1.1 Códigos de estado ).

Sin embargo, esto se basa en la validación en el momento de la presentación, en lugar de diferirla como en su caso de uso. Las otras respuestas tienen soluciones adecuadas para ese escenario.

Licenciado bajo: CC-BY-SA con atribución
No afiliado a StackOverflow
scroll top