Todo sobre mis APIs

En esta ocasión presentamos estrategias de desarrollo de APIs REST, así como los distintas herramientas y lenguajes de especificación que nos van a permitir generar código y documentación. También repasamos herramientas de testing para APIs.

2. Byteflair
http://byteflair.com
Daniel Cerecedo
@dcerecedo
Victor Hernandez
@uvehachebe

3. AgendaAgenda
Arquitectura
Arquitectura REST
Developer UX
REST sobre HTTP
Hypermedia APIs
Vistas Adaptativas
Actualizaciones &
Concurrencia
I18n
Lenguajes de especificación
Herramientas de prueba
Byteflair

4. ArquitecturaArquitectura
Byteflair

5. 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 REST
Cliente/ServidorCliente/Servidor

6. 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 REST
Sin estadoSin estado

7. Cliente
Elimina total o parcialmente algunas de las interacciones
 Rendimiento de red
 Rendimiento percibido por el usuario
Cache
Servidor
Cache
Byteflair
Arquitectura RESTArquitectura REST
CacheableCacheable

8. 1.Identificación por URIs
2.Mensajes autodescriptivos
3.Manipulación a través de representaciones
4.HATEOAS
 Simplicidad
Byteflair
Arquitectura RESTArquitectura REST
Interfaz uniformeInterfaz uniforme

9. Cliente
Cada capa solo conoce a su vecina
 Simplicidad
 Latencia
Cache
Servidor
Cache
Proxy
Cache
Balanceador
Byteflair
Arquitectura RESTArquitectura REST
Por capasPor capas

10. Developer UXDeveloper UX
El desarrollador como destinatario del
contenido, no los navegadores
Byteflair

11. ¿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 HTTP
Ludwig Wittgenstein

12. REST sobre HTTPREST sobre HTTP
Separar la representación del recurso de los
metadatos de la petición
Representación Body
→
Metadatos Headers
→
Byteflair

13. REST sobre HTTPREST sobre HTTP
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

14. REST sobre HTTPREST sobre HTTP
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

15. REST sobre HTTPREST sobre HTTP
Byteflair
Error HTTP
Error de negocio
Error técnico

16. HypermediaHypermedia
Byteflair

17. HypermediaHypermedia
Byteflair

18. HypermediaHypermedia
Byteflair

19. HypermediaHypermedia
Modela el dominio del problema
Identifica los recursos del dominio
Identifica las transiciones de estado del sistema
Distingue entre estructura interna y lo que expones como recurso
Byteflair
 ¡No expongas la base de datos!

20. HypermediaHypermedia
Recursos del dominio
VehiclesDrivers
UsersOwners
Sessions
Transiciones de estado
Crear recursos
Filtrar recursos
Asignar conductor a vehículo
Activar sesión: conductor + vehículo
Desactivar sesión
Byteflair

21. HypermediaHypermedia
Definir los formatos de representación
Mime Types
Definir roles para cada control hypermedia
Rel Types
Convenciones semánticas
POST, PUT, GET, DELETE
Byteflair

22. HypermediaHypermedia
GET /
Headers
Link:
<https://api.domain.com/vehicles>; rel=”vehicles”:
<https://api.domain.com/users>; rel=”users”:
<https://api.domain.com/sessions>; rel=”sessions”
Body
...
Byteflair

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

24. HypermediaHypermedia
GET /sessions/1374
Body
{….
“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

25. HypermediaHypermedia
GET /vehicles/1
Body
{….
“owner”:”https://api.domain.com/users/1”
}
Relation types specify the role of the link
Byteflair

26. HypermediaHypermedia
El cliente debe descubrir su nivel de acceso a
cada recurso
Options
Byteflair

27. HypermediaHypermedia
Convenciones
Rel Types, Media Types, Methods, Status Codes
Byteflair
..o qué debe saber
el desarrollador
de antemano
Las convenciones se convierten en acoplamiento

28. HypermediaHypermedia
Byteflair
HALHAL
http://stateless.co/hal_specification.html

29. HypermediaHypermedia
Como proveedor, minimiza el número
de cosas que debes saber de antemano
sobre un API
Byteflair

30. HypermediaHypermedia
No se consigue
desacoplar un
cliente de
su servidor
con magia
Byteflair

31. Vistas adaptativasVistas adaptativas
Byteflair

32. Vistas adaptativasVistas adaptativas
Distintos contextos de seguridad
requieren vistas diferentes sobre los
mismos datos
Byteflair

33. Un administrador debe poder ver todos los datos de un
usuario
Un usuario puede ver todos sus datos
Un usuario solo puede ver los datos públicos de los
demás usuarios
Scenario
Byteflair
Vistas adaptativasVistas adaptativas

34. /users/{id}
/owner/users/{id}
/admin/users/{id}
Una URI por cada rol de seguridad
Scenario
Byteflair
Vistas adaptativasVistas adaptativas

35. Descomponer el recurso
Dar 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
Vistas adaptativasVistas adaptativas

36. Un único recurso
Múltiples vistas sobre el mismo recurso
Seleccionamos la vista en runtime
Scenario
/users/{id}
Byteflair
Vistas adaptativasVistas adaptativas

37. Actualizaciones & Concurrencia
Byteflair

38. 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 & Concurrencia
Scenario
Byteflair

39. Comparar la representación que llega con el recurso
existente...
Actualizaciones & ConcurrenciaActualizaciones & Concurrencia
Byteflair

40. Comparar la representación que llega con el recurso
existente...
Si no son iguales, rechazar...
Actualizaciones & ConcurrenciaActualizaciones & Concurrencia
Byteflair
Podemos usar el ETAG

41. Comparar la representación que llega con el recurso
existente...
Si no son iguales, rechazar...
Si es posible, informar al cliente de las violaciones
Actualizaciones & ConcurrenciaActualizaciones & Concurrencia
Byteflair

42. Peticiones asíncronasPeticiones asíncronas
Byteflair

43. 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íncronas

44. Peticiones asíncronasPeticiones asíncronas
Scenario
Ok
Needs
Repair
Repaired
Awaiting
Byteflair
Los camiones se revisan regularmente y se seleccionan
para reparación

45. Peticiones asíncronasPeticiones asíncronas
Scenario
Ok
Needs
Repair
Repaired
Bajo mi control
Awaiting
Byteflair
Los camiones se revisan regularmente y se seleccionan
para reparación

46. Peticiones asíncronasPeticiones asíncronas
Scenario
Ok
Needs
Repair
Repaired
Bajo mi control
Awaiting
PUT /trucks/6/repair
202 Accepted
Byteflair
Los camiones se revisan regularmente y se seleccionan
para reparación

47. Si existen peticiones que consumen mucho tiempo...
Byteflair
Peticiones asíncronasPeticiones asíncronas

48. Si existen peticiones que consumen mucho tiempo...
las hacemos asíncronas!
Byteflair
Peticiones asíncronasPeticiones asíncronas

49. Speaking in silverSpeaking in silver
i18ni18n
Byteflair

50. Speaking in silverSpeaking in silver
i18ni18n
GET /i18n/es_ES
Body
{
“country” : “ES”,
“lang”: “es”,
“data” : { “key”: “localized message”, ….}
}
Byteflair

51. Byteflair
API API SpecificationSpecification

52. Byteflair
API API BlueprintBlueprint
API API SpecificationSpecification
Apiary.io
Primera versión: Abril 2013
Objetivos:
Simplicidad
Interacción y dialogo entre desarrolladores y consumidores

53. Byteflair
API API BlueprintBlueprint
API API SpecificationSpecification
Apiary editor:
https://app.apiary.io
Editor local:
Atom + Snowcrash + Aglio + Atom plugin

54. Byteflair
API API BlueprintBlueprint
API API SpecificationSpecification
Ejemplo

55. Byteflair
API API BlueprintBlueprint
API API SpecificationSpecification
Gist  : https://gist.github.com/victorhernandezbermejo/9d5a9448a487a71dd503
Blueprint: http://docs.bfphonebook.apiary.io/

56. Byteflair
API API BlueprintBlueprint
API API SpecificationSpecification
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

57. Byteflair
API API BlueprintBlueprint
API API SpecificationSpecification
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

58. Byteflair
SwaggerSwagger
API 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.

59. Byteflair
SwaggerSwagger
API API SpecificationSpecification
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

60. Byteflair
SwaggerSwagger
API API SpecificationSpecification
Enlaces:
Sitio web:
http://swagger.io/
En github:
https://github.com/swagger-api
Especificación del lenguaje:
https://github.com/swagger-api/swagger-spec

61. Byteflair
SwaggerSwagger
API API SpecificationSpecification
Ejemplo

62. Byteflair
SwaggerSwagger
API API SpecificationSpecification
Gist  : https://gist.github.com/victorhernandezbermejo/efd8093ec45db46836cf

63. Byteflair
RAMLRAML
API 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.

64. Byteflair
RAMLRAML
API API SpecificationSpecification
API Designer:
http://api-portal.anypoint.mulesoft.com/raml/api-designer
Imagen Docker:
https://github.com/Byteflair/docker-raml-editor
docker pull byteflair/raml-editor
docker run -d -p <port>:9013 byteflair/raml-editor

65. Byteflair
RAMLRAML
API API SpecificationSpecification
Enlaces:
Sitio web:
http://raml.org/
En github:
https://github.com/raml-org
Especificación del lenguaje:
https://github.com/raml-org/raml-spec

66. Byteflair
RAMLRAML
API API SpecificationSpecification
Ejemplo

67. Byteflair
RAMLRAML
API API SpecificationSpecification
Gist  : https://gist.github.com/victorhernandezbermejo/f5db381cb4cf395f47d1

68. Byteflair
ComparativaComparativa
API API SpecificationSpecification
Comunidad de usuarios 
+
 Watch Star Fork Questions
Apiary Blueprint115 1,891 561 489
Swagger 221 2,482 822 1,541
RAML 96 1,080 77 120
Datos a fecha 16/03/2015

69. Byteflair
ComparativaComparativa
API API SpecificationSpecification
Comunidad de usuarios 
+
 Watch Star Fork Questions
Apiary Blueprint115 1,891 561 489     
Swagger 221 2,482 822 1,541     
RAML 96 1,080 77 120     

70. Byteflair
ComparativaComparativa
API API SpecificationSpecification
Apiary BlueprintSwagger RAML
 
+
              

71. Byteflair
ComparativaComparativa
API API SpecificationSpecification
Apiary BlueprintSwagger RAML
 
+
              
Curva de aprendizaje              

72. Byteflair
ComparativaComparativa
API API SpecificationSpecification
Apiary BlueprintSwagger RAML
 
+
              
Curva de aprendizaje              
Mock server               

73. Byteflair
ComparativaComparativa
API API SpecificationSpecification
Apiary BlueprintSwagger RAML
 
+
              
Curva de aprendizaje              
Mock server               
Reutilización de código              

74. Byteflair
ComparativaComparativa
API API SpecificationSpecification
Apiary BlueprintSwagger RAML
 
+
              
Curva de aprendizaje              
Mock server               
Reutilización de código              
Expresividad               

75. Byteflair
ComparativaComparativa
API API SpecificationSpecification
Apiary BlueprintSwagger RAML
 
+
              
Curva de aprendizaje              
Mock server               
Reutilización de código              
Expresividad               
Concisión               

76. Byteflair
ComparativaComparativa
API API SpecificationSpecification
Apiary BlueprintSwagger RAML
 
+
              
Curva de aprendizaje              
Mock server               
Reutilización de código              
Expresividad               
Concisión               
Herramientas               

77. Byteflair
ComparativaComparativa
API API SpecificationSpecification
Apiary BlueprintSwagger RAML
 
+
              
Curva de aprendizaje              
Mock server               
Reutilización de código              
Expresividad               
Concisión               
Herramientas               
Documentación               

78. Byteflair
ComparativaComparativa
API API SpecificationSpecification
Apiary BlueprintSwagger RAML
 
+
              
Curva de aprendizaje              
Mock server               
Reutilización de código              
Expresividad               
Concisión               
Herramientas               
Documentación               
Total 27  27  35 

79. Byteflair
API API SpecificationSpecification
ConclusionesConclusiones

80. Byteflair
ToolsTools
DemoDemo

81. Byteflair
ToolsTools
LinksLinks
Postman: http://www.getpostman.com/
Runscope: https://www.runscope.com/
Soap UI: http://www.soapui.org/

82. Byteflair
ToolsTools
GistsGists
Gist  : https://gist.github.com/victorhernandezbermejo/854271c55cba55749c1d

83. “Las armas deben adaptarse a
tus cualidades personales y
debes ser capaz de
manejarlas”
Miyamoto Mushashi
Byteflair

84. ?
ThanksThanks GraciasGracias
http://byteflair.com
Daniel Cerecedo
@dcerecedo
Victor Hernandez
@uvehachebe