El documento es una introducción al concepto de API REST, explicando sus fundamentos, arquitecturas y el uso de HTTP como protocolo para la comunicación. Se detalla la estructura de los recursos, métodos y el manejo de errores, así como aspectos de seguridad y autenticación en servicios REST. Además, se menciona la importancia de un diseño coherente y las buenas prácticas para el versionado y la gestión de APIs.

1. WORKSHOP I
INTRODUCCIÓN A API REST

2. ¿QUÉ ES UNA API?

3. APPLICATION PROGRAMING INTERFACE
Conjunto de subrutinas, funciones y
procedimientos que ofrece cierta biblioteca
para ser utilizado por otro software como una
capa de abstracción.
¿QUÉ ES UNA API?
La cara de una plataforma
hacia el mundo exterior.
=

4. Nos abstraemos de las capas más internas de
la plataforma.
¿QUÉ ES UNA API?
LO QUE IMPORTA ES EL QUÉ, NO EL CÓMO

5. ¿QUÉ ES UNA API?
http://www.smashew.com/

6. PLATAFORMA MONOLÍTICA

7. PLATAFORMA DISTRIBUIDA
API
API
API

8. ¿QUÉ ES REST?

9. ¿ES UN PÁJARO?
¿UN AVIÓN?
¿UN PROTOCOLO?
¿UN LENGUAJE?
¿JSON?
¿XML?
¿HTTP?
¿SOA?
NO, ES UN...
¿QUÉ ES REST?

10. Representational State Transfer es un modelo de arquitectura software orientada a construir servicios web escalables
conforme a una serie de buenas prácticas.
Los principales son:
● Separación y responsabilidades en modelo consumidor y servidor.
● Modelo en base a recursos identificados de forma unívoca y homogénea.
● Operaciones atómicas sin estado.
● Conjunto de operaciones acotadas: CRUD.
Y, ¿sobre qué protocolo se implementa todo esto?
¿QUÉ ES REST?

11. Un servicio web tiene como objetivo fundamental enviar datos de un punto A a un punto B.
HTTP es un protocolo perfecto para esto:
● Entidades / Nombres → Recursos identificados por una URI.
● Operaciones / Verbos → Métodos HTTP.
● Resultados → Códigos de estado HTTP.
● Metadatos → Cabeceras HTTP.
● Representaciones → Body HTTP.
Realmente, ¿hace falta más?
PROTOCOLO: HTTP

12. REST VS SOAP

13. ESTADOS HTTP
2XX 3XX
4XX 5XX

14. FORMATO: JSON VS XML
● JSON, XML, HTML, texto plano… son formas
de representar la información.
● REST puede trabajar con cualquiera de ellas.
● JSON encaja muy bien en la filosofía REST de
hacer las cosas lo más sencillas posible.
● JavaScript es uno de los lenguajes más
populares.
● XML es un lenguaje pensado para ser
interpretado por máquinas. JSON es más
human-friendly.

15. EJEMPLO
QUEREMOS CONSTRUIR UNA
PLATAFORMA E-LEARNING CON UN
MODELO DE ARQUITECTURA RESTful.

16. RECURSOS
Los recursos con las entidades (nombres) sobre las que operar.
Se identifican con URLs:
http://api.e-learning.com/{recurso}/{id}
http://api.e-learning.com/users
http://api.e-learning.com/users/41123
http://api.e-learning.com/courses
http://api.e-learning.com/courses/64362

17. RECURSOS: DEBATES
ANTIPATRÓN:
http://api.e-learning.com/user?id=41123
ANIDAMIENTO:
http://api.e-learning.com/course/636/module/312
PLURALIZACIÓN:
http://api.e-learning.com/courses
http://api.e-learning.com/course

18. Los métodos son las operaciones (verbos) que podemos realizar sobre los recursos. Están acotadas por los métodos
disponibles en HTTP.
POST: create
GET: read
PUT: update
DELETE: delete
La mayoría de escenarios se pueden resolver con estas cuatro operaciones.
MÉTODOS

19. GET
GET http://api.e-learning.com/courses
200 OK
[
{
"id":1,
"name":"Introducción a REST",
"description":"Conceptos fundamentales de las APIs REST: recursos, métodos, status...",
"duration":3,
"modules":[ ...]
},
{
"id":2,
"name":"Python para desarrolladores Java",
"description":"...",
"duration":4,
"modules":[ ...]
}, ...
]

20. GET
GET http://api.e-learning.com/courses/1
200 OK
{
"id":1,
"name":"Introducción a REST",
"description":"Conceptos fundamentales de las APIs REST",
"duration":3,
"modules":[...]
}

21. POST
POST http://api.e-learning.com/courses
{
"name":"Introducción a Spark",
"description":"Análisis de datos masivos en memoria con Spark",
"duration":10,
"modules":[...]
}
201 CREATED
Location: /courses/42113

22. PUT
PUT http://api.e-learning.com/courses/42113
{
"name":"Introducción a Spark" ,
"description":"Análisis de datos masivos en memoria con Spark" ,
"duration":15,
"Modules":[...]
}
200 OK

23. DELETE
DELETE http://api.e-learning.com /courses/42113
204 NO CONTENT
ó
200 OK
{
"name":"Introducción a Spark",
"description":"Análisis de datos masivos en memoria con Spark",
"duration":15,
"modules":[...]
}

24. HEAD → Preguntar si un recurso existe.
OPTIONS → Devuelve los métodos disponibles sobre un recurso.
PATCH → Actualizaciones parciales.
OTROS MÉTODOS

25. Se utilizan para metadatos y protocolo a nivel de aplicación.
Accept: text/plain
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: es-ES
Cookie: $version=1; skin= new;
Content-Length: 12312
Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ==
Content-Type: application/x-www-form-urlencoded
Date: Mon, 27 Apr 2015 08:12:31 GM
Authorization: Basic bXl1c2VyOm15cGFzcw==
Location: /users/123
CABECERAS

26. Formato en el que vienen representados los datos, se negocia con las cabeceras Accept (petición) y Content-Type
(petición y respuesta).
application/json
application/xml
application/octet-stream
text/plain
text/html
application/x-www-form-urlencoded
multipart/form-data
CONTENIDO

27. Normalmente se pasan como query parameters y se utilizan para añadir criterios adicionales de filtrado, ordenación, paginado…
GET http://api.e-learning.com/courses?name=Spark&page_size=10&sort=+name
[
{
"id":1,
"name":"Introducción a Spark",
...
},
{
...
]
PARÁMETROS

28. Además del status code 4XX ó 5XX correspondiente, hay que devolver un body informativo:
{
"errors":[
{
"userMessage":"Sorry, resource does not exist",
"internalMessage":"No course found in the database",
"code":34
}
]
}
GESTIÓN DE ERRORES

29. ¿Qué ocurre si lanzas una nueva versión de tu API?
→ VERSIONADO
http://api.e-learning.com/v1
http://api.e-learning.com/v2
...
VERSIONADO

30. HATEOAS
Hypermedia as the Engine of Application State
{
"id":1,
"name":"Introducción a REST",
"description":"Conceptos fundamentales de las APIs REST: recursos, métodos, status...",
"duration":3,
"modules":[
{
"id":32,
"name":"HATEOAS",
"links":[
{
"rel":"self",
"href":"/v1/modules/32"
}
]
}
...
]
}

31. BENEFICIOS: HOMOGENEIDAD
/listUsers?id=123
/getUsers?id=123
/findUsers?user_id=123
/users/find/123
/users/get_by_id/123
/deleteUser
/users: GET y POST
/users/{id}: GET, PUT y DELETE

32. BENEFICIOS: SIN ESTADO → ESCALABLE
/enroll_user_course?course=1&user=2
1. Comprobar si existe curso
2. Comprobar si existe usuario
3. Comprobar si quedan plazas libres en el curso
4. ...
Asignar usuario al curso.
HEAD /user/1
GET /courses/1
POST /course/1/user/1
...

33. Q&A
Descanso 10 minutos

34. CASOS DE USO: BACK END APP MÓVIL
APIREST
/scores
/level/610
/gamestats
GET
POST
POST
GET

35. CASOS DE USO: BACK END APP MÓVIL
APIREST
/account
/transactions
/transfer
GET
POST
POST
GET

36. CASOS DE USO: MACHINE TO MACHINE
MYSTORE
/checkout
/pay
/user
/payment
POST
GET
POST
POST

37. CASOS DE USO: MACHINE TO MACHINE
MYAPP
/service2
/ec2/new
/service3
/service4
/service5
/service6
/service1
/storage
POST
PUT

38. CASOS DE USO: DATA API (READ ONLY)
/nextweek
/today
/cities/madrid
GET
GET
GET
GET

39. ESTADÍSTICAS
http://www.programmableweb.com/news/97-games-apis-secondlife-internet-video-archive-and-eve-online/2012/05/30

40. ESTADÍSTICAS
http://www.programmableweb.com/news/97-games-apis-secondlife-internet-video-archive-and-eve-online/2012/05/30

41. ESTADÍSTICAS

42. TIPOLOGÍA DE APIs
● Servicios back-end Internet.
● e-Commerce.
● Backoffice.
● Financieros.
● Datos (solo lectura).
● ...

43. SEGURIDAD

44. SEGURIDAD EN SERVICIOS REST
1. Esquemas (RFC 2617)
Basic
Digest Schemes (OAuth 1.0)
Bearer Token Schemes (OAuth2)
Custom
2. Autenticación por Api Key
3. Autenticación por Token
Header:
Authorization: ….
../?api-key=…&secret-key=….
../?token=….

45. ESQUEMA: BÁSICO
PROS:
● Simple de utilizar (en el cliente).
● Soportado por todos los servidores y frameworks
de programación (y navegadores!!!!).
● Utiliza la cabecera Authentication
● Estándar http.
● No requiere peticiones CORS
CONS:
● Base64 no es un un tipo de cifrado!
● Solo es seguro sobre HTTPs
● Es más lento… (https).
base64string = base64.encode( username + “:” + password)
req.add_header(" Authorization", "Basic " + base64string)
req.send()

46. ESQUEMA: DIGEST (i.e. OAuth 1.0)
PROS:
● Pensada para autenticación con 3ros de
manera segura.
● Garantiza la autenticidad end-to-end del
mensaje.
● No es necesario utilizar HTTPS.
● Las contraseñas nunca se envían en las
peticiones.
● No es vulnerable a Man-In-The-Middle.
CONS:
● Complejo de implementar tanto el cliente como servidor.
● Complejo de entender y utilizar.
● Los clientes de navegadores no son buenos para retener
los tokens y credenciales necesarios.
POST /1/statuses/update.json
Authorization:
OAuth oauth_consumer_key="xvz1evFS4wEEPTGEFPHBog",
oauth_nonce="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg",
oauth_signature="tnnArxj06cWHq44gCs1OSKk%2FjLY%3D",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1318622958",
oauth_token="370773112-GmHxMAgYyLbNEtI……...EyMZeS9weJAEb",
oauth_version="1.0"

47. ESQUEMA: DIGEST (i.e. OAuth 1.0)
usuario
app
tercero
1. usuario accede a la app y pide
conectar con tercero 2. app pide al tercero un token de
autorización
3. tercero genera el token y el
secret token
4. app construye link de auth y lo
envía al usuario
5. usuario autoriza al app mediante link
6. app accede a los datos del
cliente mediante el token

48. ESQUEMA: BEARER TOKEN (OAUTH 2.0)
PROS:
● Utiliza estándar para generación de tokens (JWT) que expiran.
● Más sencillo que ESQUEMA: DIGEST.
● No requiere acceso a la contraseña del usuario.
CONS:
● Susceptible a ataques Man-In-The-Middle.
● Requiere renovación del token, proceso posiblemente complejo.
POST /events HTTP/1.1
Host: my-server.com
Authorization: Bearer AbCdEf123456
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML,
like Gecko; Gmail Actions)

49. ESQUEMA: CUSTOM
PROS:
● Personalización total tanto del flujo de
comunicaciones, como de la generación de
claves (siempre utilizando la cabecera
Authorization).
CONS:
● Hay que generar documentación exquisita y
clientes/librerías propietarias que debes
entregar a tus consumidores.
● Puede incrementar la complejidad.

50. AUTENTICACIÓN API KEY
PROS:
● Ideal para API m2m.
● Se puede combinar con otros tipos de auth como basic/digest/bearer.
CONS:
● No se recomienda guardar el api KEY, en clientes inseguros como Navegadores (HTML/JS).
Ejemplo:
ID : YLNVXG091ZO1BSANZ5U6DCTIX
Secret: gtaMCCJoFnEu3dDlkxmdgtaMCCJoFnEu3dDlkxmd+92iaY

51. AUTENTICACIÓN POR TOKEN
PROS:
● Ideal para API m2m.
CONS:
● No se recomienda guardar el api KEY, en clientes inseguros como Navegadores (HTML/JS).
1. Request: POST /token
?grant_type=password&username=username&password=password
2. Response:
{
“token_type":"auth.service1",
“expires_in":6000,
"refresh_token":"U9fhc2aNkUuwiFRDfrRo",
"parameter1":"value1”,
"access_token":" 6tivaTH33cafRZI5mOIu"
}
3. GET /service1 HTTP/1.1
Authorization: Bearer 6tivaTH33cafRZI5mOIu

52. MODELING LANGUAGES
...ioDocs, WADL, WSDL

53. WSDL 1.0/2.0

54. RAML

55. SWAGGER

56. BLUEPRINT

57. TOOLING!
Generación de
DOC
Generación de
API Java
Generación de
Pruebas
Unitarias
Generación de
pruebas
funcionales
Definición de
interfaz REST
Generación de
Cliente
(javascript)
ANÁLISIS
Generación de
pruebas carga
DEV FRONTEND
DEV FRONTEND
DEV BACKEND DEV BACKEND
DEV BACKEND
DEV BACKEND

58. TOOLING!
Generación de
DOC
Generación de
API
Generación de
Pruebas
Unitarias
Generación de
pruebas
funcionales
Definición
de interfaz
REST
Generación
de Cliente
(javascript)
API Designer
Generación de
pruebas carga
API Console
API Notebook
REST Postman
SoapUI plugin
JMeter / Tsung
JAX-RS/Spring
Restify

59. API MANAGEMENT: WHAT?
Servicio
Servicio backend consumidores
API
API MANAGER APP

60. API MANAGEMENT: FEATURES
● API Security: SSL, PKI, threat protection, schema validation, encryption, signatures, etc.
● API Lifecycle governance: Versioning, etc.
● Analytics & traffic monitoring.
● API Identity: API key, OAuth, SAML, LDAP, MFA, token translation & management.
● API metering, Billing and Monetization
● Developer Center: Client ID/app key generation, interactive API console.
● API Discovery: Catalog, search and provisioning.
● API Orchestration: Adaptation of multiple services, workflow operations, branching policies, etc.
● Operational Integration: System monitoring, clustering, scalability, migration.

61. API MANAGEMENT

62. PYTHON: DJANGO REST

63. NODEJS
restify

64. JAVA

65. MICROSERVICIOS: EVOLUCIÓN
http://es.slideshare.net/ErnestoHernandezRodriguez/arquitecturas-de-microservicios-codemotion-2014

66. PATRONES: ADAPTER

67. PATRONES: ADAPTER

68. PATRONES: ADAPTER (NETFLIX)

69. PATRONES: WEBHOOKS
polling NO!!
NO
NO!!
no
ALGO PARA
MI?
ALGO PARA
MI?
ALGO PARA
MI?
ALGO PARA
MI?
NOOOO!!!!
NO!!!!!!
cliente servidor

70. PATRONES: WEBHOOKS
OK
SI TE LLEGA ALGO
ENVIAMELO AL
BUZÓN!
LLEGÓ
ALGO
servidorcliente

71. INICIATIVAS: ODATA
OData
El protocolo OData (Open Data Protocol) facilita la creación de servicios de datos REST, que pueden ser identificados por URI (uniform
resource identifiers) únicas, para ser publicados y consumidos por clientes web.
Protocolos
Convenios
Lenguaje de definición de esquemas común
Formato JSON Format
Vocabulario estándar

72. GET /statuses/retweets_of_me
GET /friends/ids
POST /friendships/destroy
GET /blocks/list
GET /favorites/list
POST /favorites/destroy
POST /favorites/create

73. GET /v1/payments/payment/<Payment-Id>
POST /v1/payments/orders/<Order-Id>/authorize
POST /v1/payments/orders/<Order-Id>/do-void
POST /v1/payments/orders/<Order-Id>/capture
POST /v1/payments/capture/<Capture-Id>/refund
GET /v1/invoicing/invoices?<Query-String>
GET /v1/invoicing/invoices/<Invoice-Id>/qr-code

74. SHOW ME YOUR API!
● programmableweb.com
● github.com/WhiteHouse/api-standards
● dev.twitter.com/rest/public
● developers.bbva.com

75. www.beeva.com
hablemos@beeva.com