233 votos

Cómo crear RESTO URLs sin verbos?

Yo estoy luchando para determinar cómo diseñar descanso Url. Yo soy todo para el descanso del enfoque de la utilización de direcciones Url con los sustantivos y los verbos no no entender cómo hacer esto.

Estamos creando un servicio para implementar una calculadora financiera. La calculadora tiene un montón de parámetros que vamos a cargar a través de un archivo CSV. Los casos de uso implicaría:

  1. Subir nuevos parámetros
  2. Recibe las últimas parámetros
  3. Obtener los parámetros para una determinada fecha de negocios
  4. Hacer un conjunto de parámetros activo
  5. Validar un conjunto de parámetros

Deduzco que el descanso del criterio sería la siguiente Url:

/parameters
/parameters/12-23-2009

Usted podría conseguir los primeros tres casos de uso con:

  1. POST en el que incluir el archivo de parámetros en la petición post
  2. OBTENER de primera URL
  3. CONSEGUIR de segunda URL

Pero ¿cómo hacerlo de la 4ª y 5ª caso de uso sin un verbo? No se necesitan Url como:

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

??

892voto

Bob Aman Puntos 19110

Principios generales para el buen URI diseño de:

  • No utilice parámetros de consulta para alterar el estado de
  • No usar mayúsculas caminos si usted puede ayudar; en minúscula es el mejor
  • No uso específico de la implementación de las extensiones en su Uri (.php, .py, .pl, etc.)
  • No caer en la RPC con su URIs
  • ¿ Límite de su URI de espacio tanto como sea posible
  • ¿ Mantener a los segmentos de la ruta corta
  • ¿ Que prefieren /resource o /resource/; crear redireccionamientos 301 de la que no usa
  • Hacer uso de los parámetros de consulta para la sub-selección de un recurso; es decir. la paginación, consultas de búsqueda
  • Hacer mover las cosas de la URI que debe ser en un encabezado HTTP o un cuerpo

(Nota: no he dicho "de Descanso URI de diseño"; URIs son esencialmente opaco en el RESTO.)

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

  • No utilizar nunca LLEGAR a alterar el estado; esta es una gran manera de tener la Googlebot arruinar su día
  • No utilice PONER menos de que se actualicen todo un recurso
  • No utilice PONER a menos que usted también puede legítimamente hacer un GET en el mismo URI
  • No usar POST para recuperar la información que es de larga duración o que podría ser razonable caché
  • No realizar una operación que no es idempotente con PONER
  • Hacer uso para OBTENER tanto como sea posible
  • Hacer uso de CORREOS en la preferencia de PONER en la duda
  • Hacer uso de CORREOS cada vez que tiene que hacer algo que se siente RPC-como
  • Hacer uso PONER para las clases de recursos que son más grandes o jerárquica
  • Hacer uso de ELIMINAR en la preferencia de POST para quitar recursos
  • Hacer uso de CONSEGUIR cosas como los cálculos, a menos que su aporte es de gran tamaño, en cuyo caso el uso de CORREOS

Principios generales de la web de diseño de servicio con HTTP:

  • No poner los metadatos en el cuerpo de una respuesta que debe ser en un encabezado
  • No poner los metadatos en un recurso independiente, a menos que incluso se podría crear una sobrecarga considerable
  • Hacer uso de la correspondiente código de estado
    • 201 Created después de la creación de un recurso de recursos; debe existir en el momento en que se envía la respuesta
    • 202 Accepted después de realizar una operación con éxito o la creación de un recurso de forma asincrónica
    • 400 Bad Request , cuando alguien hace una operación en información que es claramente falsa; para su aplicación, esto podría ser un error de validación; en general, la reserva de 500 para no detectada excepciones
    • 401 Unauthorized cuando alguien tiene acceso a su API, ya sea sin el suministro de una necesaria Authorization de encabezado o cuando las credenciales dentro de la Authorization no son válidos; no utilizar este código de respuesta si usted no espera que las credenciales a través de un Authorization de encabezado.
    • 403 Forbidden cuando alguien tiene acceso a su API en una manera que podría ser malicioso o si los mismos no autorizado
    • 405 Method Not Allowed cuando alguien usa POST cuando se debería haber utilizado PONER, etc
    • 413 Request Entity Too Large cuando alguien intenta enviarle un inaceptable archivo de gran tamaño
    • 418 I'm a teapot cuando se intenta colar el café con un vaso de agua
  • Hacer uso de la caché de las cabeceras siempre que pueda
    • ETag encabezados son buenas cuando usted puede reducir fácilmente un recurso de un valor hash
    • Last-Modified debe indicar a usted que mantener alrededor de una marca de tiempo de cuando los recursos son actualizados es una buena idea
    • Cache-Control y Expires debe ser dada valores sensatos
  • Hacer todo lo posible para honrar la caché de las cabeceras de la petición (If-None-Modified, If-Modified-Since)
  • Hacer uso de redirecciones cuando tienen sentido, pero debe ser raro que un servicio web

Con respecto a tu pregunta específica, POST debe ser utilizado para el #4 y #5. Estas operaciones de caer bajo el "RPC-como" pauta anterior. Para #5, recuerde que el POST no necesariamente tiene que usar Content-Type: application/x-www-form-urlencoded. Esto podría fácilmente ser un JSON o CSV carga.

55voto

yfeldblum Puntos 42613

Quizás algo como:

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

{ "active": true }

15voto

Rich Apodaca Puntos 7327

Siempre parece que se necesita un nuevo verbo, pensar acerca de la activación de ese verbo en un sustantivo en su lugar. Por ejemplo, la vuelta de 'activar' en 'activación', y 'validar' en 'validación'.

Pero sólo a partir de lo que he escrito yo diría que su aplicación tiene mucho más grandes problemas.

En cualquier momento un recurso llamado 'parámetro' es la propuesta, se debe enviar hasta las banderas rojas en cada miembro del equipo de proyecto en mente. 'parámetros', literalmente, puede aplicar a cualquier recurso; no es lo suficientemente específico.

¿Qué hace exactamente un 'parámetro' representan? Probablemente una serie de cosas diferentes, cada una de las cuales debe tener un recurso independiente dedicado a ella.

Otra manera de llegar a esto - cuando usted habla de su aplicación con los usuarios finales (los que supuestamente saben poco acerca de la programación) ¿cuáles son las palabras que ellos mismos usan repetidamente?

Esas son las palabras que debe ser el diseño de su aplicación.

Si aún no han tenido esta conversión con los futuros usuarios de parada de todo ahora mismo y no escribir otra línea de código hasta que lo haga! Sólo entonces, su equipo tiene una idea de lo que debe ser construido.

Yo no sé nada acerca de software financiero, pero si tuviera que adivinar, diría que algunos de los recursos podría ir a por nombres tales como "Informe", "Pago", "Transferencia"y "Moneda".

Hay un buen número de libros en esta parte del proceso de diseño de software. Dos que puedo recomendar son de Dominio Impulsado por el Diseño y el Análisis de los Patrones.

10voto

Breton Puntos 9625

El diseño de su url no tiene nada que ver con el hecho de que su aplicación es de Descanso o no. la frase de "reposo" URL es por lo tanto absurdo.

Creo que deberíamos hacer un poco de lectura adicional sobre lo que el DESCANSO es en realidad. RESTO trata de la URL como opaco, y como tal no sabe lo que hay en ellos, si hay verbos o sustantivos o lo que sea. Aún puede que quiera diseñar su URL, sino que se trata de la interfaz de usuario, no de DESCANSO.

Dicho esto, le permite llegar a tu pregunta: Los dos últimos casos no son de Descanso, y no se ajustan a cualquier tipo de descanso esquema. Esos son lo que se podría llamar RPC. Si usted es serio sobre el RESTO tendrás que replantear cómo funciona la aplicación desde cero. O eso, o abandonar RESTO y acaba de hacer su aplicación como un RPC de la aplicación.

Hrmmm tal vez no.

La idea aquí es que usted tiene que tratar todo como un recurso, por lo que una vez que un conjunto de parámetros de una URL que se puede hacer referencia a él desde, solo hay que añadir

[parametersurl]/validationresults

post [paramatersurl]

cuerpo: {comando:"activar"}

pero, de nuevo, que activan la cosa es RPC, no de DESCANSO.

4voto

Darrel Miller Puntos 56797

El activar y validar los requisitos son situaciones en las que usted está tratando de cambiar el estado de un recurso. No es diferente que hacer un pedido de "completado", o alguna otra solicitud "enviado". Existen numerosos métodos para modelar este tipo de estado de cambio, pero un cambio que me parece que funciona a menudo es crear recursos de colección de recursos de un mismo estado y, a continuación, mover los recursos entre las colecciones afectar el estado.

por ejemplo. Crear algunos recursos, tales como,

/ActiveParameters
/ValidatedParameters

Si usted desea hacer un conjunto de parámetros activo, añadir que el conjunto de la ActiveParameters colección. Usted podría pasar el conjunto de parámetros como el cuerpo de la entidad, o podría pasar una url como un parámetro de consulta, de la siguiente manera:

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

La misma cosa se puede hacer con el /ValidatedParameters. Si los Parámetros no son válidos, a continuación, el servidor puede devolver "Bad Request" a la petición de añadir los parámetros de la recolección de la validación de los parámetros.

Iteramos.com

Iteramos es una comunidad de desarrolladores que busca expandir el conocimiento de la programación mas allá del inglés.
Tenemos una gran cantidad de contenido, y también puedes hacer tus propias preguntas o resolver las de los demás.

Powered by: