REST API Workshop Introduction

WORKSHOP I
INTRODUCCIÓN A API REST

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.
=

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

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

PLATAFORMA DISTRIBUIDA
API
API
API

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

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?

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

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.

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

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

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

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

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":[ ...]
}, ...
]

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

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

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

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

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

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

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

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,
...
},
{
...
]
PARÁMETROS

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

¿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

HATEOAS
Hypermedia as the Engine of Application State
{
"id":1,
"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"
}
]
}
...
]
}

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

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
...

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

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

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

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

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

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

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

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=….

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()

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"

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

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)

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.

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

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

MODELING LANGUAGES
...ioDocs, WADL, WSDL

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

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

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

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.

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

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

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

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

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

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

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

www.beeva.com
hablemos@beeva.com

REST API Workshop Introduction

Recomendados

Recomendados

Más contenido relacionado

La actualidad más candente

La actualidad más candente (20)

Destacado

Destacado (18)

Similar a REST API Workshop Introduction

Similar a REST API Workshop Introduction (20)

Más de BEEVA_es

Más de BEEVA_es (20)

Último

Último (15)

REST API Workshop Introduction