taller definición de apis

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

admin@cloudappi.net ·

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

Twitter

YouTube

Flickr

Amazon Product

Advertising

Facebook

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: admin@apiaddicts.org

Web:

http://www.meetup.com/APIAddicts

Siguenos en:

➢ Linkedin: ApiAddicts

➢ Twitter: @apiaddicts

➢ Facebook: APIAddicts

➢ Meetup: APIAddicts

Contacta