REST es el principio arquitectónico subyacente de la web. Lo sorprendente de la web es el hecho de que los clientes (navegadores) y los servidores pueden interactuar de formas complejas sin que el cliente sepa de antemano nada sobre el servidor y los recursos que alberga. La restricción clave es que el servidor y el cliente deben acordar los medios utilizados, que en el caso de la web es HTML .
Una API que se adhiere a los principios de REST no requiere que el cliente sepa nada sobre la estructura de la API. Más bien, el servidor necesita proporcionar cualquier información que el cliente necesite para interactuar con el servicio. Un formulario HTML es un ejemplo de esto: el servidor especifica la ubicación del recurso y los campos obligatorios. El navegador no sabe de antemano dónde enviar la información, y no sabe de antemano qué información enviar. Ambas formas de información son completamente proporcionadas por el servidor. (Este principio se llama HATEOAS : Hypermedia como el motor del estado de la aplicación ).
Entonces, ¿cómo se aplica esto a HTTP y cómo se puede implementar en la práctica? HTTP está orientado a verbos y recursos. Los dos verbos en el uso principal son GETy POST, que creo que todos reconocerán. Sin embargo, el estándar HTTP define varios otros como PUTy DELETE. Estos verbos luego se aplican a los recursos, de acuerdo con las instrucciones proporcionadas por el servidor.
Por ejemplo, imaginemos que tenemos una base de datos de usuarios administrada por un servicio web. Nuestro servicio utiliza un hipermedia personalizado basado en JSON, para el cual asignamos el tipo MIME application/json+userdb(también puede haber un application/xml+userdby application/whatever+userdb, muchos tipos de medios pueden ser compatibles). El cliente y el servidor han sido programados para comprender este formato, pero no saben nada el uno del otro. Como Roy Fielding señala:
Una API REST debería dedicar casi todo su esfuerzo descriptivo a definir los tipos de medios utilizados para representar los recursos y dirigir el estado de la aplicación, o para definir nombres de relaciones extendidas y / o marcado habilitado para hipertexto para los tipos de medios estándar existentes.
Una solicitud para el recurso base /podría devolver algo como esto:
Solicitud
GET /
Accept: application/json+userdb
Respuesta
200 OK
Content-Type: application/json+userdb
{
"version": "1.0",
"links": [
{
"href": "/user",
"rel": "list",
"method": "GET"
},
{
"href": "/user",
"rel": "create",
"method": "POST"
}
]
}
Por la descripción de nuestros medios, sabemos que podemos encontrar información sobre recursos relacionados en secciones llamadas "enlaces". Esto se llama controles hipermedia . En este caso, podemos deducir de esa sección que podemos encontrar una lista de usuarios haciendo otra solicitud para /user:
Solicitud
GET /user
Accept: application/json+userdb
Respuesta
200 OK
Content-Type: application/json+userdb
{
"users": [
{
"id": 1,
"name": "Emil",
"country: "Sweden",
"links": [
{
"href": "/user/1",
"rel": "self",
"method": "GET"
},
{
"href": "/user/1",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/1",
"rel": "delete",
"method": "DELETE"
}
]
},
{
"id": 2,
"name": "Adam",
"country: "Scotland",
"links": [
{
"href": "/user/2",
"rel": "self",
"method": "GET"
},
{
"href": "/user/2",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/2",
"rel": "delete",
"method": "DELETE"
}
]
}
],
"links": [
{
"href": "/user",
"rel": "create",
"method": "POST"
}
]
}
Podemos decir mucho de esta respuesta. Por ejemplo, ahora sabemos que podemos crear un nuevo usuario POSTal /user:
Solicitud
POST /user
Accept: application/json+userdb
Content-Type: application/json+userdb
{
"name": "Karl",
"country": "Austria"
}
Respuesta
201 Created
Content-Type: application/json+userdb
{
"user": {
"id": 3,
"name": "Karl",
"country": "Austria",
"links": [
{
"href": "/user/3",
"rel": "self",
"method": "GET"
},
{
"href": "/user/3",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/3",
"rel": "delete",
"method": "DELETE"
}
]
},
"links": {
"href": "/user",
"rel": "list",
"method": "GET"
}
}
También sabemos que podemos cambiar los datos existentes:
Solicitud
PUT /user/1
Accept: application/json+userdb
Content-Type: application/json+userdb
{
"name": "Emil",
"country": "Bhutan"
}
Respuesta
200 OK
Content-Type: application/json+userdb
{
"user": {
"id": 1,
"name": "Emil",
"country": "Bhutan",
"links": [
{
"href": "/user/1",
"rel": "self",
"method": "GET"
},
{
"href": "/user/1",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/1",
"rel": "delete",
"method": "DELETE"
}
]
},
"links": {
"href": "/user",
"rel": "list",
"method": "GET"
}
}
Tenga en cuenta que estamos utilizando diferentes verbos HTTP ( GET, PUT, POST, DELETEetc.) para manipular estos recursos, y que el único conocimiento se presume por parte del cliente es nuestra definición de los medios.
Otras lecturas:
(Esta respuesta ha sido objeto de una buena cantidad de críticas por perder el punto. En su mayor parte, ha sido una crítica justa. Lo que describí originalmente estaba más en línea con la forma en que REST se implementó generalmente hace unos años cuando yo primero escribí esto, en lugar de su verdadero significado. Revisé la respuesta para representar mejor el significado real).
