Está en la página 1de 9

Guas para las API de servicios

Portal Inteligente Medelln


Documentacion de la Arquitectura de Software
Juan G. Lalinde-Pulido
Claudia M. Zea
Luis F. Londono
Nicolas Hock
Sergio A. Monsalve

Departamento de Informatica y Sistemas


Universidad EAFIT
20 de septiembre de 2013

Captulo 1
Guas para las API de servicios
En este documento se proveen las guas y ejemplos para las API de los servicios del portal de Medelln
Digital. Esta gua fomenta la consistencia, mantenibilidad y mejores practicas a traves de los difertenes
servicios del portal.
Este documento se basa en:
White House API Standards [1]
GitHub APIs [2]
Designing HTTP Interfaces and RESTful Web Services[3]
Steve Klabnik. Designing Hypermedia APIs[4]

1.1.

Reglas Generales para Servicios RESTful

REST es un estilo de arquitectura propuesto por Roy Fielding en el ano 2000, que busca desacoplar
el cliente y el servidor de una aplicacion.[5]

1.1.1.

Restricciones

La arquitectura REST tiene cinco restricciones requeridas:


Cliente-Servidor: Una clara separacion entre el cliente el servidor. Esto implica, por ejemplo, que los
clientes no son responsables de almacenar datos y que los servidores no se encargan de la interfaz
de usuario.

Sin estado: Toda comunicacion entre el cliente y el servidor es independiente del contexto. En ninguna parte se almacena informacion sobre interacciones pasadas. Esto implica que cada peticion del
cliente al servidor debe incluir toda la informacion necesaria para contextualizar al servidor.

Cacheable: Las respuestas que enva el servidor pueden ser guardadas en cache. Debe existir un mecanismo para invalidar la respuesta y conseguir una verison mas reciente.
2

Sistema por capas: La peticion puede pasar por varios sistemas antes de generar una respuesta. Estas
pueden incluir un cache, un balanceador de carga, un proxy y finalmente el servidor. Esto tiene que
ser transparente para el cliente.

Interfaz uniforme: Simplifica y desacopla la arquitectura entre el cliente y el servidor. As, cada componente puede evolucionar de forma independiente.

Principios de la Interfaz
La interfaz uniforme debe tener en cuenta los siguientes principios:
Identificacion de Recursos: Los recursos son elementos de informacion que pueden ser accedidos por
un identificador global (URI). Esto implica que el servidor no debe enviar los registros en base
de datos crudos, sino objetos que forman parte del dominio de la aplicacion. Los recursos son
enviados en una representacion especfica (XML, JSON, HTML).
Manipulacion de los recursos a traves de las representaciones: Cuando un cliente adquiere la representacion de un recurso, tiene la informacion suficiente para modificarlo o eliminarlo en el servidor
si tiene los permisos suficientes.
Mensajes auto-descriptivos: Todos los mensajes que se transmiten entre los componentes, tienen suficiente informacion para informar como deben ser manipulados. Esto incluye, por ejemplo, el
formato (JSON, XML) en el que se espera recibir la representacion del recurso.
Hypermedia como el motor del estado de la aplicacion: HATEOAS por su nombre en ingles, significa que en todo momento, el servidor es quien enva al cliente las transiciones que puede realizar
desde el estado en el que se = encuentra. Esto implica que la u nica direccion que conoce el cliente
es la inicial (root de la API). Todas las otras peticiones se hacen dependiendo de la informacion
enviada por el servidor.

1.2.

REST Pragmatico

Aun cuando lo ideal sera tener APIs 100 % RESTful, se facilitan las siguientes excepciones:
La version de la API puede estar en la URL. No se aceptan peticiones que no especifiquen la
version.
Permita que los usuarios pidan el formato desde la URL as:

https://portal.ejemplo.com/api/v1/events.json
https://portal.ejemplo.com/api/v1/events.xml

1.3.

Identificadores de los Servicios (URLs)


Una URL identifica un recurso.
Una URL nunca tiene verbos. Siempre son sustantivos.
Usar sustantivos en plural para la consistencia.
Usar los verbos HTTP (GET, POST, PUT, DELETE) para operar sobre los recursos y colecciones.
Nunca se deben tener URLs con mas de dos niveles de profundidad:
Mal:
https://portal.ejemplo.com/api/v1/eventos/32/fotos/332/comentarios

Bien:
https://portal.ejemplo.com/api/v1/fotos/332/comentarios

La version debe ser siempre el primer parametro en la URL


https://portal.ejemplo.com/api/v32/

La version siempre tiene que ser un numero entero.


El formato debe ser de la forma
api/v3/recurso/{identificador}.{formato}

1.3.1.

Ejemplos de URLs

Buenas URLs
Una lista de eventos:
https://api.ejemplo.com/v1/eventos.json

Filtrando colecciones:

https://api.ejemplo.com/v1/eventos.json?ano=2013&order=desc
https://api.ejemplo.com/v1/picoyplaca.json?placa=2

Un solo recurso:
https://api.ejemplo.com/v1/eventos/3-pais-paisa.json

Recursos anidados: Por ejemplo, todas las fotos un evento especfico.

https://api.ejemplo.com/v1/eventos/3-pais-paisa/fotos.json

Crear una nueva foto en un evento especfico:


POST https://api.ejemplo.com/v1/eventos/3-pais-paisa/fotos.json

Malas URLs
Nombre en singular:
https://api.ejemplo.com/v1/evento/3-pais-paisa.json

Verbos en la URL:
https://api.ejemplo.com/v1/eventos/3-pais-paisa/editar

Filtros como parte de la URL:


https://api.ejemplo.com/v1/eventos/2013

1.4.

Verbos HTTP

Los verbos utilizados al realizar la peticion, daran al servidor el contexto necesario para saber que manipulacion se quiere hacer con los recursos.
HTTP MET- POST
GET
HOD
CRUD OP
CREATE
READ
/perros
Crea un perro Lista de perros
nuevo
/perros/1234
Error
Muestra el perro

PUT

DELETE

UPDATE
Actualizacion
en bloque
Si existe, actualiza el perro;
sino, error

DELETE
borra todos los
perros
borra al perro
1234

(Ejemplo de Web API Design, de Brian Mulloy, Apigee.)

1.5.

Respuestas
No poner valores en las llaves.
No exponer valores privados ni nombres especficamente internos (node, taxonomy).
Los metadatos deben ser especficos a la respuesta. No a los miembros de ella.
Todos los recursos, en colecciones o no, deben tener un identificador relacionado donde el cliente
puede pedir informacion sobre este recurso especfico.
Todas las respuestas deben tener metadata. Si es JSON, esto debe ser un objeto aparte. En ATOM
(XML) y HTML se pueden utilizar los elementos de hypermedia definidos en los estandares.
5

1.5.1.

Buena Respuesta:

GET /v1/articulos/32-nuevo-portal/etiquetas.json
{
"tags": [
{"nombre": "Medell
n Digital", "url": "https://api.ejemplo.com/v1/etiquetas/324-medellin-digital"},
{"nombre": "Innovaci
on", "url": "https://api.ejemplo.com/v1/etiquetas/24"}
],
"metadata": {
"links": [
{"rel": "self", "url": "/v1/articulos/32-nuevo-portal/etiquetas.json"},
{"rel": "articulo", "url": "/v1/articulos/32-nuevo-portal.json"}
]
}
}

1.5.2.

Mala Respuesta:

GET /v1/articulos/32-nuevo-portal/etiquetas.json
{
"tags": [
{"324": "Medell
n Digital"},
{"24": "Innovaci
on"}
]
}
GET /v1/articulos/32-nuevo-portal/etiquetas.json
{
"tags": ["Medell
n Digital", "Innovaci
on"]
}

1.5.3.

Errores

Las respuestas de errores deben incluir el codigo HTTP del error, un mensaje para los desarrolladores
y uno para los usuarios (cuando sea necesario), un codigo de error interno (si aplica), vnculos donde los
desarrolladores pueden encontrar informacion adicional (si aplica). Por ejemplo:
{
"status" : "400",
"developerMessage" : "Mensaje claro explicando al desarrollador el problema.
Dar sugerencias de como resolver el problema.",
"userMessage" : "Mensaje para mostrar a los usuarios, si es necesario.",
"errorCode" : "444444",
"mas info" : "http://www.example.gov/developer/path/to/help/for/444444,
http://drupal.org/node/444444",
}

1.5.4.

Codigos HTTP en las respuestas

HTTP tiene muchos codigos[6] para responder a las peticiones. Los mas utilizados son:
200 - OK: La operacion fue completada con e xito.
201 - Creado: Se creo un recurso (se debe enviar en la respuesta).
304 - No modificado: El cache no ha expirado.
400 - Solicitud incorrecta: La solicitud contiene sintaxis erronea y no debera repetirse.
6

401 - No autorizado: El usuario no se ha autenticado o ha fallado en hacerlo.


403 - Prohibido: La solicitud fue legal, pero el servidor se rehusa a responderla. En contraste a una
respuesta 401 No autorizado, la autentificacion no hara la diferencia.
500 - Error Interno: El servidor ha sufrido un error interno.

1.6.

Ejemplos de Peticiones y Respuestas

1.6.1.

Recursos

GET /articulos
GET /articulos/id
POST /articulos

1.6.2.

GET /articulos

GET /v1/articulos.json

{
"metadata": {
"links":{
[
{"rel": "next", "url": "https://api.ejemplo.com/v1/articulos.json?=page2"},
{"rel": "last", "url": "https://api.ejemplo.com/v1/articulos.json?=page7"},
{"rel": "self", "url": "https://api.ejemplo.com/v1/articulos.json"}
]
}
}
"articulos": [
{
"id": 1,
"url": "https://api.ejemplo.com/v1/articulos/1-hola.json",
"titulo": "La innovaci
on en Medell
n",
"contenido": "El contenido del articulo",
"tags": [],
"autor": {
"nombre": "Nicol
as Hock Isaza",
"url": "https://api.ejemplo.com/v1/autores/323.json"
},
"creado": "Agosto 20, 2013"
},
{
"id": 43,
"url": "https://api.ejemplo.com/v1/articulos/43.json",
"titulo": "Pico y Placa segundo semestre 2013",
"contenido": "El contenido del articulo",
"tags": [
{"nombre": "pico y placa", "url": "https://api.ejemplo.com/v1/etiquetas/24.json"}
],
"autor": {
"nombre": "Alejandra Montoya",
"url": "https://api.ejemplo.com/v1/autores/1.json"
},
"creado": "Juli 10, 2013"
}
]
}

1.6.3.

GET /articulos/id

GET /v1/articulos/1-hola.json
{
"metadata": {
"links":{
[
{"rel": "self", "url": "https://api.ejemplo.com/v1/articulos/1-hola.json"}
]
}
}
"articulo":{
"id": 1,
"url": "https://api.ejemplo.com/v1/articulos/1-hola.json",
"titulo": "La innovaci
on en Medell
n",
"contenido": "El contenido del articulo",
"tags": [],
"autor": {
"nombre": "Nicol
as Hock Isaza",
"url": "https://api.ejemplo.com/v1/autores/323.json"
},
"creado": "Agosto 20, 2013"
}
}

1.6.4.

POST /articulos

POST /v1/articulos.json
{
"titulo": "Un nuevo art
culo",
"contenido": "El contenido del nuevo articulo",
"autor": {
"nombre": "Juan Guillermo Lalinde"
}
"tags": [
{"nombre": "innovacion"}, {"nombre": "pico y placa"}
]
}

Bibliografa
[1] White house api standards. https://github.com/WhiteHouse/api-standards.
[2] Github apis. http://developer.github.com/v3/.
[3] Designing http interfaces and restful web services. http://goo.gl/pPlEFD.
[4] Designing hypermedia apis. http://www.designinghypermediaapis.com.
[5] Representational state transfer. http://goo.gl/ipilt.
[6] Codigos de estado http. http://goo.gl/bMUUE.