rest - tutorial - google tag manager español

¿Cómo crear URLs REST sin verbos? (8)

Estoy luchando para determinar cómo diseñar URLs tranquilos. Estoy a favor del enfoque reparador de usar URL con nombres y no verbos que no entiendan cómo hacer esto

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

Subir nuevos parámetros
Consigue los últimos parámetros
Obtener parámetros para una fecha de negocio dada
Hacer un conjunto de parámetros activos.
Validar un conjunto de parámetros.

Reconozco que el enfoque reparador sería tener las siguientes URL de tipo:

/parameters /parameters/12-23-2009

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

POST donde se incluye el archivo de parámetros en la solicitud posterior
OBTENER la primera URL
GET de la segunda URL

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

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

Cuando parezca que necesita un nuevo verbo, piense en convertir ese verbo en un sustantivo en su lugar. Por ejemplo, convierta ''activar'' en ''activación'' y ''validar'' en ''validación''.

Pero solo por lo que has escrito, diría que tu solicitud tiene problemas mucho mayores.

Cada vez que se propone un recurso llamado ''parámetro'', debe enviar señales de alerta en la mente de cada miembro del equipo del proyecto. ''parámetro'' puede aplicarse literalmente a cualquier recurso; no es lo suficientemente especifico

¿Qué representa exactamente un ''parámetro''? Probablemente hay varias cosas diferentes, cada una de las cuales debe tener un recurso separado dedicado a ello.

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

Esas son las palabras con las que deberías estar diseñando tu aplicación.

Si aún no ha tenido esta conversión con posibles usuarios, deténgalo 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 sobre esta parte del proceso de diseño del software. Dos de los que puedo recomendar son Diseño de Dominio y Patrones de Análisis .

El diseño de sus urls no tiene nada que ver con si su aplicación es REST o no. la frase "RESTful URLS" es, por lo tanto, sin sentido.

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 qué 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 se trata de IU, no de REST.

Dicho esto, lleguemos a tu pregunta: los dos últimos casos no son REST completos y no encajan en ningún tipo de esquema de descanso. 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 debe tratar todo como un recurso, por lo que una vez que un conjunto de parámetros tiene una URL a la que puede referirse, simplemente agregue

obtener [parametersurl] / validationresults

post [paramatersurl]

cuerpo: {comando: "activar"}

Pero, de nuevo, esa cosa activa es RPC, no REST.

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. Necesitas profundizar en lo que llamas 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 RESTO. Como dijo alguien más, sus requisitos anteriores suenan más XMLRPC. Si estás intentando REST necesitas 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.

Los requisitos de activación y validación son situaciones en las que está intentando 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 encuentro 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, crear algunos recursos tales como,

/ActiveParameters /ValidatedParameters

Si desea activar un conjunto de parámetros, agregue ese conjunto 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 los parámetros / 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.

Principios generales para un buen diseño de URI:

No use los parámetros de consulta para alterar el estado
No uses caminos mixtos si puedes evitarlo; en minúsculas es mejor
No use extensiones específicas de la implementación en sus URI (.php, .py, .pl, etc.)
No caigas en RPC con tus URIs
Limita tu espacio URI tanto como sea posible
Mantener segmentos de ruta cortos
Prefiere ya sea /resource o /resource/ ; cree 301 redirecciones desde la que no usa
Utilice los parámetros de consulta para la subselección de un recurso; es decir paginación, consultas de búsqueda
Mueva 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:

Nunca uses GET para alterar 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 utilice 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 PUT
Utilice GET tanto como sea posible
Utilice POST en lugar de PUT en caso de duda
Use POST siempre que tenga que hacer algo que se sienta como RPC
Use PUT para clases de recursos que sean más grandes o jerárquicas
Utilice DELETE en lugar de POST para eliminar recursos
Use GET para cosas como cálculos, a menos que su entrada sea grande, en cuyo caso use POST

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

No coloque 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 crearía una sobrecarga significativa
Utilice 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 asincrónica
- 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 Unauthorized cuando alguien accede a su API sin proporcionar el encabezado de Authorization necesario o cuando las credenciales dentro de la Authorization no son válidas; no utilice este código de respuesta si no espera credenciales a través de un encabezado de Authorization .
- 403 Forbidden cuando alguien accede a su API de una manera que puede ser malintencionada o si no está autorizada
- 405 Method Not Allowed cuando alguien usa POST cuando debería haber usado PUT, etc.
- 413 Request Entity Too Large cuando alguien intenta enviarle un archivo inaceptablemente grande
- 418 I''m a teapot cuando intento preparar café con una tetera
Utilice encabezados de almacenamiento en caché siempre que pueda
- ETag encabezados de ETag son buenos cuando puede reducir fácilmente un recurso a un valor hash
- Last-Modified debe indicarle que mantener una marca de tiempo de cuando los recursos se actualizan es una buena idea
- Cache-Control y Expires deben tener valores sensibles
Haga todo lo que pueda para honrar los encabezados de almacenamiento en caché en una solicitud ( If-None-Modified , If-Modified-Since )
Utilice 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 están bajo la guía "similar a RPC" anterior. Para # 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.

Quizás algo como:

PUT /parameters/activation HTTP/1.1 Content-Type: application/json; encoding=UTF-8 Content-Length: 18 { "active": true }

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

Hacer parámetros activos y / o validarlos:

> 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'': ''...''} < } <

Edit: De hecho, el URI habría evitado que las solicitudes GET permanezcan en idempotent.

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 de 400 Bad Request si los datos enviados no son válidos y la solicitud debe modificarse antes de volver a enviarse ( códigos de estado HTTP / 1.1 ).

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.