Define y desarrolla tu primera API

Marco Antonio Sanz

¿Quienes somos?

Grupo de meetuphttp://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❏ El Mundo Big Data y las APis❏ El Mundo Cloud y las APis❏ 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 75admin@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?

1) Realizar un documento funcional2) Realizar el diseño de la API3) Realizar una implementación fake 4) Implementar la API5) Validar la API6) Generar documentación para developers7) 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

■ 500: Error interno 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

Crear:

POST http://apitest.cloudsystems.es/users

Modificar:

PUT http://apitest.cloudsystems.es/users/23

Eliminar:

DELETE http://apitest.cloudsystems.es/users/23

Consultar:

GET http://apitest.cloudsystems.es/users

Consultar un usuario:

GET http://apitest.cloudsystems.es/users/23

Segundo nivel

GET http://apitest.cloudsystems.es/users/23/cars

urls

Restful

Crear un usuariorequest:

POST http://apitest.cloudsystems.es/usersbody:

{"name": "Marco", "firstname": "Polo", "lastname": "2", "address": { "street": "blab bla", "number": "2" }}response:Header:HTTP CODE: 201

Body:{"result": {

"info": "user created" }, "data": {

"id": "23"}}

Ejemplo

Restful

Obtener usuarios:Request:

GET http://apitest.cloudsystems.es/usersResponse:Header: HTTP CODE: 200Body: { "result": { "info": "OK"},

"data": { "users": [ { "name": "Marco","firstname": "Polo",

"address": {"street": "blabbla"}}, { "name": "Prueba","firstname": "ww",

"address": {"street": "blab bla" }}]}

} }

Ejemplo

Restful

Actualizar un usuarioRequest:

PUT http://apitest.cloudsystems.es/users/23body:

{lastname:”González”}Response:Header: HTTP CODE: 200

Body:{

“result”:{“info”:”user updated”},{“data”:””}

}

Ejemplo

Restful

Eliminar un usuarioRequest:

DELETE http://apitest.cloudsystems.es/users/23Response:Header: 200 OKBody:{

"result": { "info": "user deleted"

},"data": ""

}

Ejemplo

Restful

● Fields● Paging● Expand● Method● Orderby

Parámetros

Definición de Apis

➢ Devuelve los atributos seleccionados

Fields

Parámetros

request:

GET /users?fields=name

response:

header:

http code 200

body:

Original:

"data": [ {"user": {

"name": "marco",

“dni”:”123123123”,

“age”:”12”

“phones”:[“1222”,”222”]

}}]}

Response:

"data": [ {"user": {

"name": "marco"

}}]}

➢ Parámetro limit / offset: Se debe mostrar un offset y el número de elementos a devolver. request:

GET /users?limit=100&offset=200

response:

header:

http code 200/206

body:

Restful

{

"paging": {

"total": 10,

"num": 3,

"page_size": 100,

"next": "/users?limit=100&offset=300",

"previous": "/users?limit=100&offset=100",

"last": "/users?limit=100&offset=900",

"first": "/users?limit=100&offset=0"

},

"data": [

{"user": { "name": "marco"}}

]

}

Paginación

Restful

request:

POST /users?method=put

body:

body:

{"user": {

"name": "pepe"

}}

Response:

header: 200 OK

body:

{"result": {

"info": "user updated"

}}

➢Algunos clientes de API pueden no soportar realizar las peticiones PUT, DELETE.

PUT y DELETE

➢ Permite devolver el segundo o tercer nivel de un json

Expand

Restful

Por defecto

request:

GET /users

response:

header: 200 OK

body:

{"data": [

{"user": { "name": "marco"

}}

]}

request:

GET /users?expand=address

response:

header: 200 OK

body:

{"data": [

{"user": { "name": "marco"

“address”:{

“street”:”Calle velasco” }

}}

]}

➢ Permite indicar el orden de la lista a devolver

Orderby

Restful

request:

GET /users?sortby=name DESC

response:

header: 200 OK

body:

{"data": [

{"user": { "name": "marco"}}

{"user": { "name": "laura"}}

]}

ORIGINAL

request:

GET /users?orderby=name DESC

response:

header: 200 OK

body:

{"data": [

{"user": { "name": "laura"}}

{"user": { "name": "marco"}}

]}

➢ Cabecera Authentication- Oauth 1.0 / 2.0- Basic- Hmac

Seguridad

Restful

request:

GET /users?expand=address

header:

Authentication Basic dXN1YXJpbzpwYXNzd29yZA==

response:

header: 200 OK

body:

{"data": [

{"user": { "name": "marco"

]}

Base64 (usuario:password)

- Accept- Content-type

Formatos de entrada/salida

Restful

request:

GET /users?expand=address

header:

Content-Type: application/xml

Accept: application/json

response:

header: 200 OK

body:

{"data": [

{"user": { "name": "marco"

]}

Base64 (usuario:password)

Las Apis deben versionarse como cualquier producto software. No tiene por qué coincidir con la implementación y suele indicarse en la url.

METHOD /<version>/<resource>

Versionado

Restful

request:

GET /1/users?expand=address

header:

Content-Type: application/xml

Accept: application/json

response:

header: 200 OK

body:

{"data": [

{"user": { "name": "marco"

]}

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

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

/{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

Desarrollo de una implementación con las interfaces de entrada y salida.

Implementado Fake

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