todo sobre mis apis

Byteflair

http://byteflair.com

Daniel Cerecedo@dcerecedo

Victor Hernandez@uvehachebe

http://byteflair.com/

https://twitter.com/dcerecedo

https://twitter.com/uvehachebe

AgendaAgenda

ArquitecturaArquitectura RESTDeveloper UXREST sobre HTTPHypermedia APIsVistas Adaptativas

Actualizaciones & ConcurrenciaI18nLenguajes de especificaciónHerramientas de prueba

Byteflair

ArquitecturaArquitectura

Byteflair

Separación de responsabilidades de presentación y procesamiento

Portabilidad de la interfaz de usuario

Simplicidad del servidor

Capacidad de modificar los componentes por separado

ServidorCliente

Byteflair

Arquitectura RESTArquitectura RESTCliente/ServidorCliente/Servidor

Servidor

Mensajes autodescriptivos: semántica, datos, metadatos y contexto

Cliente2:Cliente

Cliente1:Cliente

Visibilidad Fiabilidad Escalabilidad

Rendimiento de red

Control sobre el comportamiento del cliente

Byteflair

Arquitectura RESTArquitectura RESTSin estadoSin estado

Cliente

Elimina total o parcialmente algunas de las interacciones

Rendimiento de red

Rendimiento percibido por el usuario

Cache

Servidor

Cache

Byteflair

Arquitectura RESTArquitectura RESTCacheableCacheable

1.Identificación por URIs2.Mensajes autodescriptivos3.Manipulación a través de representaciones4.HATEOAS

Simplicidad

Byteflair

Arquitectura RESTArquitectura RESTInterfaz uniformeInterfaz uniforme

Cliente

Cada capa solo conoce a su vecina

Simplicidad

Latencia

Cache

Servidor

Cache

Proxy

Cache

Balanceador

Byteflair

Arquitectura RESTArquitectura RESTPor capasPor capas

Developer UXDeveloper UX

El desarrollador como destinatario del contenido, no los navegadores

Byteflair

¿Porqué REST sobre HTTP?¿Porqué REST sobre HTTP?

Byteflair

“Los límites de mi lenguaje son los límites de mi nundo”

Todo el mundo habla HTTPLudwig Wittgenstein

REST sobre HTTPREST sobre HTTP

Separar la representación del recurso de los metadatos de la petición

Representación Body→Metadatos Headers→

Byteflair


Utiliza el HTTP Status Code para dar información acerca del resultado de la petición

2xx Ok→4xx El cliente ha hecho algo mal→

5xx El servidor ha fallado →

Byteflair


Utiliza los HTTP Status Codes existentes que mejor se adapten a la situación

Añade información específica cuando se produzca un error

Byteflair


Byteflair

Error HTTP

Error de negocio

Error técnico

HypermediaHypermedia

Byteflair


Modela el dominio del problemaIdentifica los recursos del dominio

Identifica las transiciones de estado del sistemaDistingue entre estructura interna y lo que expones como recurso

Byteflair

¡No expongas la base de datos!

HypermediaHypermediaRecursos del dominio

Vehicles DriversUsers Owners

SessionsTransiciones de estado

Crear recursosFiltrar recursos

Asignar conductor a vehículoActivar sesión: conductor + vehículo

Desactivar sesiónByteflair


Definir los formatos de representaciónMime Types

Definir roles para cada control hypermediaRel Types

Convenciones semánticasPOST, PUT, GET, DELETE

Byteflair

HypermediaHypermediaGET /HeadersLink: <https://api.domain.com/vehicles>; rel=”vehicles”: <https://api.domain.com/users>; rel=”users”: <https://api.domain.com/sessions>; rel=”sessions”Body...

Byteflair


GET /vehiclesHeadersLink: <https://api.domain.com/vehicles?page=1&size=20>; rel=”next”Body[ {... }, {…}, ...] Control links

Byteflair


GET /sessions/1374Body{ ….

“vehicle”:”https://api.domain.com/vehicles/1”,“driver”:”https://api.domain.com/users/1”

}

También son control links.

Aplica las convenciones para obtener el significado completo!!

Byteflair


GET /vehicles/1Body{ ….

“owner”:”https://api.domain.com/users/1”}

Relation types specify the role of the link

Byteflair


El cliente debe descubrir su nivel de acceso a cada recurso

Options

Byteflair


ConvencionesRel Types, Media Types, Methods, Status Codes

Byteflair

..o qué debe saber

el desarrollador

de antemano

Las convenciones se convierten en acoplamiento


Byteflair

HALHAL

http://stateless.co/hal_specification.html


Como proveedor, minimiza el número de cosas que debes saber de antemano

sobre un API

Byteflair


No se consigue desacoplar un

cliente de su servidorcon magia

Byteflair

Vistas adaptativasVistas adaptativas

Byteflair


Distintos contextos de seguridad requieren vistas diferentes sobre los

mismos datos

Byteflair

Un administrador debe poder ver todos los datos de un usuario

Un usuario puede ver todos sus datosUn usuario solo puede ver los datos públicos de los

demás usuarios

Scenario

Byteflair


/users/{id}/owner/users/{id}/admin/users/{id}

Una URI por cada rol de seguridad

Scenario

Byteflair


Descomponer el recursoDar diferentes niveles de acceso a cada recurso

Scenario

/users/{id}/users/{id}/my-private-data/users/{id}/data-about-me-only-the-admin-knows

Byteflair


Un único recursoMúltiples vistas sobre el mismo recurso

Seleccionamos la vista en runtime

Scenario

/users/{id}

Byteflair


Actualizaciones & Concurrencia

Byteflair

Dos clientes tratan de actualizar el mismo recurso de forma concurrente

La representación es el estado de la aplicación

Debemos evitar que la segunda petición actualice el recurso a partir de una representación obsoleta

Actualizaciones & ConcurrenciaActualizaciones & ConcurrenciaScenario

Byteflair

Comparar la representación que llega con el recurso existente...

Actualizaciones & ConcurrenciaActualizaciones & Concurrencia

Byteflair


Si no son iguales, rechazar...


Byteflair

Podemos usar el ETAG


Si no son iguales, rechazar...Si es posible, informar al cliente de las violaciones


Byteflair

Peticiones asíncronasPeticiones asíncronas

Byteflair

Como identificamos peticiones intrínsecamente asíncronas?

Existen transiciones de estado fuera del control del cliente

No tiene sentido devolver una representación por que no conocemos el estado del recurso tras la llamada

Byteflair


Peticiones asíncronasPeticiones asíncronasScenario

Ok

NeedsRepair

Repaired

Awaiting

Byteflair

Los camiones se revisan regularmente y se seleccionan para reparación


Ok

NeedsRepair

Repaired

Bajo mi controlAwaiting

Byteflair



Ok

NeedsRepair

Repaired

Bajo mi controlAwaiting

PUT /trucks/6/repair202 Accepted

Byteflair


Si existen peticiones que consumen mucho tiempo...

Byteflair


Si existen peticiones que consumen mucho tiempo...

las hacemos asíncronas!

Byteflair


Speaking in silverSpeaking in silveri18ni18n

Byteflair

Speaking in silverSpeaking in silveri18ni18n

GET /i18n/es_ESBody{

“country” : “ES”,“lang”: “es”,“data” : { “key”: “localized message”, ….}

}

Byteflair

Byteflair

API API SpecificationSpecification

Byteflair

API API BlueprintBlueprintAPI API SpecificationSpecification

Apiary.io

Primera versión: Abril 2013

Objetivos: Simplicidad Interacción y dialogo entre desarrolladores y consumidores

Byteflair


Apiary editor:https://app.apiary.io

Editor local:Atom + Snowcrash + Aglio + Atom plugin

https://app.apiary.io/

Byteflair


Ejemplo

Byteflair


Gist : https://gist.github.com/victorhernandezbermejo/9d5a9448a487a71dd503

Blueprint: http://docs.bfphonebook.apiary.io/

https://gist.github.com/victorhernandezbermejo/9d5a9448a487a71dd503

http://docs.bfphonebook.apiary.io/

Byteflair


Enlaces: Sitio web:

https://apiblueprint.org/ En github:

https://github.com/apiaryio/api-blueprint Especificación del lenguaje:

https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md

https://apiblueprint.org/

https://github.com/apiaryio/api-blueprint

https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md

Byteflair


Algunas herramientas

Apiary: http://apiary.io

Dredd: https://github.com/apiaryio/dredd

Drakov: https://www.npmjs.com/package/drakov

Dredd: https://github.com/apiaryio/dredd

Aglio: https://github.com/danielgtaylor/aglio

http://apiary.io/

https://github.com/apiaryio/dredd

https://www.npmjs.com/package/drakov

https://github.com/apiaryio/dredd

https://github.com/danielgtaylor/aglio

Byteflair

SwaggerSwaggerAPI API SpecificationSpecification

Reverb

Primera versión: Julio 2011

Objetivos: En un principio documentación de APIs ya existentes. En su versión 2.0 cambiaron el enfoque hacia el diseño y la

especificación.

Byteflair


Swagger editor:http://editor.swagger.io/

En local:https://github.com/Byteflair/docker-swagger-editor

docker pull byteflair/swagger-editor docker run -d -p <port>:9000 byteflair/swagger-editor

http://editor.swagger.io/

https://github.com/Byteflair/docker-swagger-editor

Byteflair


Enlaces: Sitio web:

http://swagger.io/ En github:

https://github.com/swagger-api Especificación del lenguaje:

https://github.com/swagger-api/swagger-spec

http://swagger.io/

https://github.com/swagger-api

https://github.com/swagger-api/swagger-spec

Byteflair


Ejemplo

Byteflair


Gist : https://gist.github.com/victorhernandezbermejo/efd8093ec45db46836cf

https://gist.github.com/victorhernandezbermejo/efd8093ec45db46836cf

Byteflair

RAMLRAMLAPI API SpecificationSpecification

Mulesoft

Primera versión: Septiembre 2013

Objetivos: Dar un mayor peso a la especificación del API Poder obtener información de todos los actores involucrados lo antes

posible.

Byteflair


API Designer:http://api-portal.anypoint.mulesoft.com/raml/api-designer

Imagen Docker: https://github.com/Byteflair/docker-raml-editor

docker pull byteflair/raml-editordocker run -d -p <port>:9013 byteflair/raml-editor

http://api-portal.anypoint.mulesoft.com/raml/api-designer

https://github.com/Byteflair/docker-raml-editor

Byteflair


Enlaces: Sitio web:

http://raml.org/ En github:

https://github.com/raml-org Especificación del lenguaje:

https://github.com/raml-org/raml-spec

http://raml.org/

https://github.com/raml-org

https://github.com/raml-org/raml-spec

Byteflair


Ejemplo

Byteflair


Gist : https://gist.github.com/victorhernandezbermejo/f5db381cb4cf395f47d1

https://gist.github.com/victorhernandezbermejo/f5db381cb4cf395f47d1

Byteflair

ComparativaComparativaAPI API SpecificationSpecification

Comunidad de usuarios +

Watch Star Fork Questions

Apiary Blueprint 115 1,891 561 489

Swagger 221 2,482 822 1,541

RAML 96 1,080 77 120

Datos a fecha 16/03/2015

Byteflair


Comunidad de usuarios +

Watch Star Fork Questions

Apiary Blueprint 115 1,891 561 489

Swagger 221 2,482 822 1,541

RAML 96 1,080 77 120

Byteflair


Apiary Blueprint Swagger RAML +

Byteflair



Curva de aprendizaje

Byteflair




Mock server

Byteflair




Mock server

Reutilización de código

Byteflair




Mock server


Expresividad

Byteflair




Mock server


Expresividad

Concisión

Byteflair




Mock server


Expresividad

Concisión

Herramientas

Byteflair




Mock server


Expresividad

Concisión

Herramientas

Documentación

Byteflair




Mock server


Expresividad

Concisión

Herramientas

Documentación

Total 27 27 35

Byteflair

API API SpecificationSpecificationConclusionesConclusiones

Byteflair

ToolsToolsDemoDemo

Byteflair

ToolsToolsLinksLinks

Postman: http://www.getpostman.com/

Runscope: https://www.runscope.com/

Soap UI: http://www.soapui.org/

http://www.getpostman.com/

https://www.runscope.com/

http://www.soapui.org/

Byteflair

ToolsToolsGistsGists

Gist : https://gist.github.com/victorhernandezbermejo/854271c55cba55749c1d

https://gist.github.com/victorhernandezbermejo/854271c55cba55749c1d

“Las armas deben adaptarse a tus cualidades personales y

debes ser capaz de manejarlas” Miyamoto Mushashi

Byteflair

?ThanksThanks GraciasGracias

http://byteflair.com

Daniel Cerecedo@dcerecedo

Victor Hernandez@uvehachebe

http://byteflair.com/

https://twitter.com/dcerecedo

https://twitter.com/uvehachebe

todo sobre mis apis

Software