taller definición de apis
DESCRIPTION
A veces, parece fácil definir una API pero la experiencia indica que la mayor parte de los problemas vienen precisamente de la mala definición de la misma. En el taller de definición de Apis, aprenderemos a definir correctamente una APi Restful, caules son los parámetros aconsejables a tener en cuenta, y se analizará un ejemplo de una API con un servicio GET, POST, PUT y DELETE. Para realizar el taller se utilizará el lenguaje RAML y la herramienta api designer de Mulesoft.TRANSCRIPT
Taller de Definición de APIs
Marco Antonio Sanz
¿Quienes somos?
Grupo de meetup
http://www.meetup.com/API-Addicts/
Meetups realizados
❏ MADA. Metodología ágil de
definición de APIs
❏ Taller: Definición de APIs
❏ Taller: Desarrolla tu primera API
❏ Seguridad en las APIs
❏ Las APis en el mundo Big Data
❏ Las APis en el mundo Cloud
❏ Apis como modelo de negocio
❏ Define y desarrolla tu primera API
Marco Antonio Sanz:http://es.linkedin.com/pub/marco-antonio-sanz-molina-prados/18/335/97/
Patrocinadores
¿qué nos ofrece?
➢ know - how de apis
➢ Experiencia en el gobierno de Apis
➢ Ejemplos de arquitecturas
➢ Experiencia en el mundo Cloud
Calle Velasco 13
Tlf: 658 89 75 75
www.cloudappi.net
Al pensar en una API, hay que
pensar en desarrollar productos. Es
un traje para varios clientes, por lo
que a todos no les puede quedar
bien.
Un backend se desarrolla pensando
en tu cliente, es un traje hecho a
medida.
API Backend
¿Qué es una API?
APIs más populares
Google Maps
YouTube
Flickr
Amazon Product
Advertising
Datos recogidos de programmable web
Crecimiento de las Apis
¿Qué es una API?
➢ Del internet de las cosas...
¿Cómo se van a conectar?
El internet de las Apis
¿Qué es una API?
1) Realizar un documento funcional
2) Realizar el diseño de la API
3) Realizar una implementación fake
4) Implementar la API
5) Validar la API
6) Generar documentación para developers
7) Generar casos de prueba (códigos de ejemplo)
8) Generar los SDks
Pasos
Definición de Apis
Hay que tener en cuenta los siguientes aspectos:
➢ Protocolo API (SOAP vs REST)
➢ Seguridad de la API,métodos de autenticación y
autorización. Pj: Basic, oauth1, aouth2…
➢ API Manager (wso2, apigee, genoa) vs ESB
(Oracle Service Bus..)
➢ Formato de datos de entrada / salida (xml, json…)
Consideraciones generales
Definición de Apis
Utiliza el protocolo HTTP para realizar las peticiones.
El estándar RESTFULL, define cómo se deben realizar las peticiones REST,
cuales son los métodos HTTP que se deben utilizar y cómo deben
estructurarse las uris para que sean user-friendly. Podemos basarnos en
https://github.com/WhiteHouse/api-standards para definir nuestra API.
Principios básicos:
➢ Una URL identifica un recurso. Por ejemplo, GET
http://testapi.cloudsystems.es/users
RestFul
Definición de Apis
➢ Uniformidad de interfaz. Los recursos se manipulan a través de las
métodos HTTP (PUT, GET, POST AND DELETE).
○ POST crea el recurso
○ PUT permite modificarlo
○ DELETE lo elimina
○ GET permite consultarlo.
○ Adicionalmente, se han introducido nuevos métodos, como
PATCH (actualización parcial de un recurso).
Principios básicos
Restful
➢ Uniformidad de salida. Los códigos HTTP de salida:
○ 1xxx: Informacional
○ 2xx: Resultado satisfactorio
■ 200: OK
■ 201: Recurso creado
○ 3xx: Redirecciones
○ 4xx: Errores de cliente
■ 400: Parámetros incorrectos
■ 404: recurso no encontrado
○ 5xx: Errores de servidor
Principios básicos
Restful
➢ Mensajes autodescriptivos: Los recursos están desacoplados de la
representación.
➢ Los mensajes se pueden devolver en varios formatos. Los
mensajes se pueden obtener en una variedad de formatos como
HTML, XML, json… Para indicar estos formatos, se puede utilizar las
cabeceras Content-Type y Accept o bién indicarlo al final de la URI.
Por ejemplo: GET testapi.cloudsystems.es/users.json
➢ Todas las peticiones son sin estado.
Principios básicos
Restful
➢ Paginación (parámetro limit / offset): Se debe mostrar un offset y el
número de elementos a devolver.
GET /users?limit=100&offset=200
➢ Atributos en la respuesta (parámetro filter). Con el fin de devolver
sólo aquellos atributos que le interesa al developer y no toda la
información, se debe introducir un parámetro que permita filtrar por
sólo unos atributos.
GET /users?fields=nombre
Consideraciones generales
Restful
➢Clientes con métodos limitados: Algunos clientes de la API
pueden no soportar realizar las peticiones POST, DELETE, GET y
PUT.
GET /users?method=DELETE
➢ Atributos con 2 niveles: Si una petición devuelve una lista de
elementos de 2 niveles se debe poder seleccionar si se quiere o no
devolver la información de segundo nivel.
GET /users?expand=address
Consideraciones generales
Restful
Crear un usuario
POST http://apitest.cloudsystems.es/users
body:
{"name": "Marco", "firstname": "Polo", "lastname": "2",
"address": { "descripcion": "blab bla", "number": "2" }}
resultado:
Header:
HTTP CODE: 201
Body:
{"result": { "info": "user created" },
"data": { "id": "23" }
}
Ejemplo
Restful
Obtener usuarios:
GET http://apitest.cloudsystems.es/users?limit=100
resultado:
Header: HTTP CODE: 200
Body:
{ "result": { "info": "OK"},
"data": {
"users": [
{ "name": "Marco","firstname": "Polo",
"address": {"descripcion": "blabbla"}},
{ "name": "Prueba","firstname": "ww",
"address": {"descripcion": "blab bla" }}]
}}
Ejemplo
Restful
Actualizar un usuario
PUT http://apitest.cloudsystems.es/users/23
body:
{lastname:”González”}
resultado:
Header:
HTTP CODE: 200
Body:
{“result”:
{“info”:”user updated”},
{“data”:””}
}
Ejemplo
Restful
Eliminar un usuario
DELETE http://apitest.cloudsystems.es/users/23
resultado:
Header:
HTTP CODE: 200
Body:
{
"result": {
"info": "user deleted"
},
"data": ""
}
Ejemplo
Restful
RAML
Api Designer
#%RAML 0.8
title: GitHub API
version: v3
baseUri: https://api.github.com
mediaType: application/json
protocols: [ HTTP, HTTPS ]
schemas:
- User: schema/user.json
Users: schema/users.json
Org: schema/org.json
Orgs: schema/orgs.json
song**
Parámetros generales de la API Existe una sección principal que describe información
general de la API, como la siguiente:
❏ title: Título de la API
❏ version: versión de la API.
❏ baseUri: url dónde se va a desplegar la API.
❏ mediaType: Tipo de dato de que va a soportar la
API
❏ protocols: Protocolos disponibles para la API
(HTTP/HTTPS)
❏ schemas: permite importar schemas json para
ser utilizados posteriormente
Documento root
RAML
❏ parámetros globales: permiten definier
parámetros comunes a varios servicios.
❏ queryParameters: Son los parámetros que
van en la query. Son los que se pasan como
get XXX/users?username=marco
❏ uriParameters: son los parámetros que van
directamente en la URI. En RestFul sólo
deberían ser identificadores de recursos.
❏ responses: Respuestas del servicio. Hay
que especificar el formato de respuesta, y
además, se puede añadir su schema y un
ejemplo. Los schemas pueden ir en json
schema o en xsd.
/users:
is: [ paged ]
get:
queryParameters:
username:
description: user to find
200:
body
application/json:
example: |
{ "result": {
"info": "user created"
}
Métodos GET
RAML
❏ body: Toda petición post debe ir
acompañada con información de entrada.
❏ responses: Respuestas del servicio. Hay
que especificar el formato de respuesta, y
además, se puede añadir su schema y un
ejemplo. Los schemas pueden ir en json
schema o en xsd.
post:
description: creates an user
body:
application/json:
example: |
{"name": "Marco", "firstname": "Polo", "lastname":
"2", "address": { "descripcion": "blab bla", "number": "2"
}}
responses:
200:
body:
application/json:
example: |
{"result": { "info": "user
created" }, "data": { "id": "23" }
}
Métodos POST
RAML
/{userId}:
uriParameters:
userId:
description: user id
delete:
description: removes a user
responses:
200:
body:
application/json:
example: |
{
"result": {
"info": "user
deleted"
},
"data": ""
}
❏ uriParameters: Permite identificar un
recurso
❏ queryParameters: Permite filtrar los
recursos
❏ responses: Respuestas del servicio. Hay
que especificar el formato de respuesta, y
además, se puede añadir su schema y un
ejemplo. Los schemas pueden ir en json
schema o en xsd.
Métodos DELETE
RAML
put:
description: updates an user
body:
application/json:
example: |
{"name": "Marco", "firstname": "Polo", "lastname":
"2", "address": { "descripcion": "blab bla", "number": "2"
}}
responses:
200:
body:
application/json:
example: |
{"result": {"info": "user
updated"},"data": ""}
❏ uriParameters: Permite identificar un
recurso
❏ queryParameters: Permite filtrar los
recursos
❏ responses: Respuestas del servicio. Hay
que especificar el formato de respuesta, y
además, se puede añadir su schema y un
ejemplo. Los schemas pueden ir en json
schema o en xsd.
❏ body: Enviar los campos a modificar. Se
debería utilizar el método HTTP PATCH
para modificaciones parciales.
Métodos PUT
RAML
Desarrollo de una implementación con las interfaces
de entrada y salida.
Implementado Fake
RAML
➢ Seguridad. API Managers
➢ Carga del sistema.
➢ Entorno (¿Desplegar en un PAAS o en un IAAS?)
➢ Estadísticas
➢ Logs del sistema
Consideraciones generales
Apis
Ruegos y preguntas
Contacta en:
Email: [email protected]
Web:
http://www.meetup.com/APIAddicts
Siguenos en:
➢ Linkedin: ApiAddicts
➢ Twitter: @apiaddicts
➢ Facebook: APIAddicts
➢ Meetup: APIAddicts
Contacta