582 votos

Entendimiento resto: Verbos, códigos de error y autenticación

Yo soy (como seguimiento a esta pregunta) buscando una forma de envolver la Api de alrededor de funciones predeterminadas en mi web basada en PHP aplicaciones, bases de datos y los CMSs.

He mirado por ahí y encontré varias "esqueleto" de marcos. Además de las respuestas a mi pregunta, no es Tónico, un RESTO marco me gusta porque es muy ligero.

Me gusta DESCANSAR mejor por su sencillez, y quisiera crear una arquitectura de API basada en ella. Estoy tratando de conseguir mi cabeza alrededor de los principios básicos y no han entendido completamente todavía. Por lo tanto, una serie de preguntas.

1. ¿Estoy entendiendo bien?

Decir que tengo un recurso de "usuarios". Yo podría configurar un número de URIs así:

/api/users     when called with GET, lists users
/api/users     when called with POST, creates user record
/api/users/1   when called with GET, shows user record
               when called with PUT, updates user record
               when called with DELETE, deletes user record

es ésta una representación correcta de un Descanso de la arquitectura hasta el momento?

2. Necesito más verbos

Crear, Actualizar y Eliminar puede ser suficiente, en teoría, pero en la práctica no tendrá la necesidad de mucho más verbos. Me doy cuenta de que estas son cosas que puede ser incrustado en una solicitud de actualización, pero son acciones específicas que puede tener específicas de los códigos de retorno y no me gustaría tirar todo en una sola acción.

Algunas que vienen a la mente en el ejemplo de usuario son:

activate_login
deactivate_login
change_password
add_credit

¿cómo puedo expresar acciones tales como las de un Descanso URL de la arquitectura?

Mi instinto sería hacer una llamada llega a una URL como

/api/users/1/activate_login 

y esperar un código de estado de la espalda.

Que se desvía de la idea de usar los verbos HTTP, sin embargo. ¿Qué te parece?

3. Cómo devolver mensajes de error y códigos de

Una gran parte del RESTO de la belleza se deriva de su uso del estándar HTTP métodos. En un error, yo emiten un encabezado con un 3xx,4xx o 5xx código de estado de error. Para una detallada descripción del error, que se puede utilizar el cuerpo (a la derecha?). Tan lejos tan bueno. Pero ¿cuál sería la forma para transmitir la propiedad de código de error que es más detallada en la descripción de lo que salió mal (por ej. "no se pudo conectar a la base de datos", o "base de datos de inicio de sesión incorrecto")? Si yo las puse en el cuerpo junto con el mensaje, tengo que analizarlo después. Hay un encabezado estándar para este tipo de cosas?

4. Cómo realizar la autenticación

  • ¿Qué sería de una clave de la API de autenticación basada siguientes RESTO principios?
  • Hay puntos fuertes en contra del uso de las sesiones de la hora de autenticar un cliente REST, aparte de que es una violación flagrante del RESTO principio? :) (solo la mitad de broma aquí, basada en la sesión de autenticación podría jugar así con mi infraestructura existente.)

EDIT: Gracias por todo su gran las respuestas de los chicos. Me voy yendo a través de ellos, mañana o el día después.

600voto

Daniel Vassallo Puntos 142049

Me di cuenta de esta cuestión de un par de días de retraso, pero creo que puedo añadir un poco de perspicacia. Espero que esto puede ser útil para su Descanso empresa.


Punto 1: ¿Estoy entendiendo bien?

Usted entiende derecha. Que es una representación correcta de un Descanso de la arquitectura. Usted puede encontrar la siguiente matriz de Wikipedia muy útil en la definición de sus nombres y verbos:


Cuando se trata de una Colección de URI como: http://example.com/resources/

  • CONSEGUIR: Lista de los miembros de la colección, que se completa con su miembro en el Uri para seguir con la navegación. Por ejemplo, una lista de todos los coches para la venta.

  • PUESTO: Significado definido como "la sustitución de toda la colección con otra colección".

  • POST: Crear una nueva entrada en la colección, donde el IDENTIFICADOR es asignado automáticamente por la colección. El IDENTIFICADOR creado normalmente se incluye como parte de los datos devueltos por esta operación.

  • ELIMINAR: Significado definido como "eliminar toda la colección".


Cuando se trata de un Miembro de la URI como: http://example.com/resources/7HOU57Y

  • CONSEGUIR: Recuperar una representación de los miembros de la colección se expresa en un tipo MIME correspondiente.

  • PUESTO: Actualizar a los miembros de la colección o crear con el ID especificado.

  • POST: Trata a los miembros como una colección en su propio derecho y crea un nuevo subordinado.

  • ELIMINAR: Eliminar a los miembros de la colección.


Punto 2: yo necesito más verbos

En general, cuando usted piensa que necesita más verbos, puede significar que, efectivamente, sus recursos y necesitan ser re-identificado. Recuerde que en el RESTO de que están actuando siempre en un recurso, o en una colección de recursos. Lo que usted elija, como la de los recursos es muy importante para su definición de API.

Activar/Desactivar el inicio de Sesión: Si va a crear una nueva sesión, a continuación, puede que desee considerar "la sesión" como el recurso. Para crear una nueva sesión, utilice el POST a http://example.com/sessions/ con las credenciales en el cuerpo. A punto de expirar el uso PUT o DELETE (tal vez dependiendo de si tiene la intención de mantener una historia de las sesiones) http://example.com/sessions/SESSION_ID.

Cambiar la Contraseña: Esta vez el recurso es "el usuario". Necesitaría un PUESTO a http://example.com/users/USER_ID con la contraseña antigua y la nueva en el cuerpo. Actúa en "el usuario" de los recursos, y un cambio de contraseña simplemente es una solicitud de actualización. Es bastante similar a la instrucción UPDATE en una base de datos relacional.

Mi instinto sería hacer una llamada llega a una URL como /api/users/1/activate_login

Esto va en contra de un mismo núcleo RESTO principio: El uso correcto de los verbos de HTTP. Cualquier solicitud GET nunca se debe dejar ningún tipo de efecto secundario.

Por ejemplo, una solicitud GET nunca debe crear una sesión en la base de datos de retorno de una cookie con un nuevo IDENTIFICADOR de Sesión, o dejar ningún residuo en el servidor. El verbo GET es como la instrucción SELECT en un motor de base de datos. Recuerde que la respuesta a cualquier solicitud con el verbo debe ser caché-poder cuando se solicite con los mismos parámetros, al igual que cuando usted solicita una página web estática.


Punto 3: Cómo devolver mensajes de error y códigos de

Considerar la 4xx o 5xx códigos de estado de HTTP como categorías de error. Usted puede elaborar el error en el cuerpo.

No se pudo Conectar a la Base de datos: / Incorrecta de la Base de datos de inicio de Sesión: En general, usted debe utilizar un error 500 de estos tipos de errores. Este es un error de servidor. El cliente no hizo nada malo. 500 errores son normalmente considerados "recuperable". es decir. el cliente puede volver a intentar la misma solicitud, y esperar que tenga éxito una vez que el servidor problemas se resuelven. Especifique los detalles en el cuerpo, por lo que el cliente será capaz de proporcionar un contexto para nosotros los seres humanos.

La otra categoría de errores sería la 4xx la familia, que en general indican que el cliente hizo algo mal. En particular, este tipo de errores que normalmente se indican al cliente que no hay necesidad de volver a intentar la solicitud tal y como es, ya que se siguen a fallar de forma permanente. es decir. las necesidades del cliente para cambiar algo antes de volver a intentarlo esta solicitud. Por ejemplo, de "Recurso no encontrado" (HTTP 404) o "Incorrecto Solicitud" (HTTP 400) errores entrarían en esta categoría.


Punto 4: ¿Cómo hacer de autenticación

Como se señaló en el punto 1, en lugar de la autenticación de un usuario, puede que quiera pensar acerca de la creación de una sesión. Usted será devuelto una nueva "ID", junto con el correspondiente código de estado HTTP (200: Acceso Concedido o 403: Acceso Denegado).

Entonces usted tendrá que pedir a sus Tranquilo servidor: "¿me los recursos para este IDENTIFICADOR de Sesión?".

No hay ningún modo autenticado por el REPOSO es apátrida: crear una sesión, pida el servidor para darle recursos a través de este IDENTIFICADOR de Sesión como parámetro, y al salir deje o caducar el período de sesiones.

77voto

Will Hartung Puntos 57465

En pocas palabras, usted está haciendo esto completamente hacia atrás.

Usted no debe estar acercándose a esto de las direcciones Url a las que usted debe utilizar. Las Url efectivamente va a venir "gratis" una vez que haya decidido sobre qué recursos son necesarios para tu sistema Y la forma en que se representan los recursos, y las interacciones entre los recursos y el estado de la aplicación.

A la cita de Roy Fielding

Una API REST debe pasar casi todos los de su descriptivo esfuerzo en la definición de la tipo de medio utilizado(s) por la representación de la de recursos y de conducción de la aplicación estado, o en la definición ampliada relación de los nombres y/o hipertexto habilitado mark-up para las ya existentes estándar de tipos de medios. Cualquier esfuerzo gastado describir lo que los métodos a utilizar en lo que Uri de interés debe ser totalmente definido en el ámbito de la las reglas de procesamiento para un tipo de medio (y, en la mayoría de los casos, ya definidas en los actuales tipos de medios). [Error aquí implica que fuera de banda la información está impulsando la interacción en lugar de hipertexto.]

La gente siempre empieza con la Uri y creo que esta es la solución, y entonces tienden a perder un concepto clave en el RESTO de la arquitectura, en particular, como el citado arriba, "Incumplimiento de lo que aquí implica que fuera de banda de la información es la conducción de la interacción en lugar de hipertexto."

Para ser honesto, muchas de ver un montón de Uri y algunas se Pone y se Pone y de los Puestos y pensar RESTO es fácil. El RESTO no es fácil. RPC a través de HTTP es fácil, mover bloques de datos de ida y vuelta a través de proxy HTTP de cargas es fácil. RESTO, sin embargo, va más allá de eso. El DESCANSO es el protocolo de agnóstico. HTTP es muy popular y apto para sistemas de DESCANSO.

RESTO vive en los tipos de medios, sus definiciones, y cómo la aplicación de las unidades de las acciones disponibles para los recursos a través de hipertexto (links, efectivamente).

Hay de vista diferentes acerca de los tipos de medios en sistemas de DESCANSO. Algunas favor específicas de la aplicación de cargas, mientras que otros como edificante a los medios existentes, los tipos de funciones que son apropiados para la aplicación. Por ejemplo, en una parte específica de esquemas de XML diseñado adecuado para su aplicación, en lugar de emplear algo como XHTML como su representación, tal vez a través de los microformatos y otros mecanismos.

Ambos enfoques tienen su lugar, creo, el XHTML trabajando muy bien en los escenarios en los que se superponen tanto el ser humano impulsada y de la máquina accionada web, mientras que el primero, más tipos de datos específicos me siento mejor facilitar las interacciones máquina a máquina. Me parece elevar el nivel de comodidad de los formatos puede hacer la negociación de contenido potencialmente difícil. "application/xml+yourresource" es mucho más específicas, como un tipo de medios que "application/xhtml+xml", ya que estos últimos pueden aplicar a muchas de las cargas que puede o no puede ser algo que una máquina cliente está realmente interesado en el, ni puede determinar sin la introspección.

Sin embargo, XHTML funciona muy bien (obviamente) en la web humano donde los navegadores web y la representación es muy importante.

La aplicación le guiará en ese tipo de decisiones.

Parte del proceso de diseño de un RESTO del sistema es el descubrimiento de la primera clase de recursos en el sistema, junto con la derivada, recursos de apoyo necesarios para apoyar las operaciones de los recursos primarios. Una vez que los recursos son descubiertos, entonces la representación de esos recursos, así como los diagramas de estado mostrando el flujo de recursos a través de hipertexto dentro de las representaciones debido a que el próximo reto.

Recordemos que cada representación de un recurso, en un sistema hipertexto, combina tanto a la representación de recurso, junto con las transiciones de estado a disposición del recurso. Considere cada uno de los recursos de un nodo en un grafo, con los lazos de unión de las líneas de salir de ese nodo a otros estados. Estos enlaces informar a los clientes no sólo lo que se puede hacer, pero lo que se requiere para que se realicen (como un buen enlace combina la URI y el tipo de papel necesario).

Por ejemplo, usted puede tener:

<link href="http://example.com/users" rel="users" type="application/xml+usercollection"/>
<link href="http://example.com/users?search" rel="search" type="application/xml+usersearchcriteria"/>

La documentación va a hablar de la rel campo denominado "usuarios", y el tipo de medios "application/xml+youruser".

Estos enlaces pueden parecer redundantes, todos están hablando a la misma URI, bastante. Pero no lo son.

Esto es así porque para los "usuarios" de la relación, ese vínculo está hablando acerca de la colección de los usuarios, y puede utilizar la interfaz uniforme para trabajar con la colección (GET para recuperar la totalidad de ellos, en ELIMINAR para eliminar a todos ellos, etc.)

Si usted POST a esta URL, usted tendrá que pasar un "application/xml+usercollection" el documento, que probablemente va a contener una única instancia de usuario en el documento, de modo que usted puede agregar el usuario, o no, tal vez, para agregar varios a la vez. Tal vez su documentación sugerir que usted puede simplemente pasar un solo tipo de usuario, en lugar de la colección.

Usted puede ver lo que la aplicación requiere para realizar una búsqueda, tal como se define por el enlace "buscar" y mediatype. La documentación para la búsqueda de los medios de comunicación tipo de decirles cómo se comporta y qué esperar resultados.

La comida para llevar aquí, sin embargo, es la Uri de los mismos, básicamente, son de importancia. La aplicación está en control de la Uri, no los clientes. Más allá de un par de 'puntos de entrada', los clientes deben confiar en la Uri de la aplicación para su trabajo.

El cliente necesita saber cómo manipular e interpretar los tipos de medios, pero no la necesidad de atención por donde va.

Estos dos enlaces son semánticamente idénticas en un cliente de ojos:

<link href="http://example.com/users?search" rel="search" type="application/xml+usersearchcriteria"/>
<link href="http://example.com/AW163FH87SGV" rel="search" type="application/xml+usersearchcriteria"/>

Así, se centran en sus recursos. Centrarse en sus transiciones de estado en la aplicación y la forma en que la mejor manera de lograr.

30voto

Stefan Tilkov Puntos 1253

re 1: Esto se ve bien hasta ahora. Recuerde devolver el URI del usuario que acaba de crear en un "Lugar:" encabezado como parte de la respuesta al POST, junto con un "201 Creado" código de estado.

re 2: la Activación a través de GET es una mala idea, y como el verbo en la URI es un diseño de olor. Usted puede ser que desee considerar la devolución de un formulario en un GET. En una aplicación Web, este sería un formulario HTML con un botón de envío; en el uso de la API del caso, es posible que desee devolver una representación que contiene una URI para PONER a para activar la cuenta. Por supuesto, usted puede incluir este URI en la respuesta en el POST del /los usuarios. Utilizando PONER asegurará de que su petición es idempotente, i.e. se puede ser enviado de nuevo si el cliente no está seguro acerca de su éxito. En general, pensar acerca de lo que los recursos que puede convertir su verbos en (una especie de "nounification de los verbos"). Pregúntate a ti mismo ¿qué es el método de su acción específica es la más estrechamente alineado con el. Por ejemplo. change_password ->; desactivar -> probablemente BORRAR; add_credit -> posiblemente POST o PUT. Punto el cliente para la adecuada URIs por incluirlos en sus representaciones.

volver a 3. No inventar nuevos códigos de estado, a menos que creas que es tan genérico que merecen ser estandarizados a nivel mundial. Trate de utilizar la más adecuada código de estado disponibles (leer acerca de todos ellos en el RFC 2616). Incluir información adicional en el cuerpo de la respuesta. Si usted realmente, realmente estás seguro de querer inventar un nuevo código de estado, piense de nuevo; si usted sigue creyendo que es así, asegúrese de que, al menos, elegir la categoría de derecho (1xx -> OK, 2xx -> informativos, 3xx -> redirección; 4xx-> error del cliente, 5xx -> error del servidor). Hice mención de que la invención de nuevos códigos de estado es una mala idea?

re 4. Si de cualquier manera posible, utilice la autenticación de marco de trabajo basado en HTTP. Echa un vistazo a la forma en la que Google hace la autenticación en GData. En general, no poner a la API de las claves de su Uri. Trate de evitar las sesiones para mejorar la escalabilidad y admite el almacenamiento en caché - si la respuesta a una solicitud difiere debido a algo que ha sucedido antes, se ha atado a sí mismo a un servidor específico instancia del proceso. Es mucho mejor el estado de la sesión en el cliente (p. ej. hacen parte de las solicitudes posteriores) o hacer explícito por convertirla en (servidor) de los recursos del estado, es decir. le dan su propia URI.

22voto

friedo Puntos 36209

1. Tienes la idea correcta acerca de cómo el diseño de sus recursos, en mi humilde opinión. Yo no cambiaría una cosa.

2. En lugar de tratar de ampliar HTTP con más verbos, considere lo que su propuesta los verbos pueden ser reducidas en los términos de la HTTP básicos de los métodos y recursos. Por ejemplo, en lugar de un activate_login verbo, usted puede configurar recursos como: /api/users/1/login/active que es un simple valor booleano. Para activar el inicio de sesión, solo PUT un documento en el que dice : 'true' o 1 o lo que sea. Para desactivar, PUT un documento que está vacía, o dice que es 0 o false.

Del mismo modo, para modificar o establecer contraseñas, simplemente haga PUTs a /api/users/1/password.

Siempre es necesario añadir algo (como un crédito) pensar en términos de POSTs. Por ejemplo, usted podría hacer una POST a un recurso como /api/users/1/credits con un cuerpo que contiene el número de créditos para agregar. Un PUT sobre el mismo recurso que podría ser utilizado para sobrescribir el valor en lugar de agregar. Un POST con un número negativo en el cuerpo restar, y así sucesivamente.

3. Me gustaría recomendar encarecidamente en contra de extender el básico de los códigos de estado HTTP. Si usted no puede encontrar uno que se adapte a su situación exactamente, elige la más cercana y poner los detalles del error en el cuerpo de la respuesta. También, recuerde que los encabezados HTTP se extensible; la aplicación puede definir todos los encabezados personalizados que te gusta. Una de las aplicaciones que he trabajado, por ejemplo, podría devolver un 404 Not Found bajo múltiples circunstancias. En lugar de hacer que el cliente de analizar la respuesta del cuerpo para la razón, hemos agregado un nuevo encabezado, X-Status-Extended, que contenía nuestro propio código de estado de las extensiones. Así que usted puede ver una respuesta como:

HTTP/1.1 404 Not Found    
X-Status-Extended: 404.3 More Specific Error Here

De esa manera, un cliente HTTP, como un navegador web, todavía se sabe qué hacer con la regular 404 del código, y una más sofisticada HTTP cliente puede elegir mirar la X-Status-Extended de encabezado para obtener información más específica.

4. Para la autenticación, recomiendo el uso de la autenticación HTTP, si puede. Pero en mi humilde opinión no hay nada de malo con el uso de la cookie de autenticación basada en si que es más fácil para usted.

11voto

jonnii Puntos 17046

Para los ejemplos que usted dijo que haría uso de los siguientes:

activate_login

POST /users/1/activation

deactivate_login

DELETE /users/1/activation

change_password

PUT /passwords (esto asume que el usuario está autenticado)

add_credit

POST /credits (esto asume que el usuario está autenticado)

Por los errores que había que volver error en el cuerpo en el formato en que recibió la solicitud, por lo que si usted recibe:

DELETE /users/1.xml

Desea enviar la copia de la respuesta en XML, lo mismo sería cierto para JSON, etc...

Para la autenticación se debe utilizar autenticación http.

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:

X