This is a short Apiary workshop I created for the OTN Tour 2017.

1. Diseño de APIs.
TALLER DE USO DE ORACLE
APIARY
S&P Solutions
Rolando Carrasco
rcarrasco@spsolutions.com.mx
Twitter: @borland_c
Blvd Manuel Avila Camacho #36-10
Lomas de Chapultepec CP 11000
+52 55 91721478

2. S&P Solutions
AGENDA
02

3. S&P Solutions
Libros Publicados
03

4. S&P Solutions
Libros Publicados
03
Nuevo
http://oracle-integration.cloud/

5. S&P Solutions
Programa de Oracle ACE. Red Expert Alliance. Developer Champion.
04
http://www.oracle.com/technetwork/community/oracle-ace/index.html
https://www.redexpertalliance.com/map-page/
https://blogs.oracle.com/developers/new-
developer-champion-program

6. API BLUEPRINT
Es un lenguaje de alto nivel para el diseño de Web APIs.
API blueprint es simple y accesible para todo aquel involucrado en
el ciclo de vida de diseño. Su sintaxis es concisa pero al mismo
tiempo expresiva.
Con API Blueprint tú puedes fácilmente modelar APIs para ser
creadas o describir APIs que ya estén desplegadas.
El API está construído para motivar el diálogo y la colaboración entre
los stakeholders de proyectos, desarrolladores y clientes en
cualquier punto del ciclo de vida de la construcción de las APIs. Al
mismo tiempo, las herramientas de API Blueprint proveen soporte
para alcanzar los objetivos de desarrollo, gobierno y entrega.
05

7. API BLUEPRINT
Un poco de historia:
06
Fuente: http://restlet.com/company/blog/2017/04/26/a-short-history-of-oai-and-api-specifications/

8. ¿Y esto?
Javadoc
07

9. API BLUEPRINT.
Contract first approach
• API blueprint abona muy bien a esta idea del contract
first approach
• Indudablemente esto nos ayuda a ser más ágiles en el
desarrollo y en la colaboración con los demás.
• Los consumidores no tienen por qué esperarnos hasta
que el desarrollo esté finalizado.
• Podemos ir entregando conforme vamos diseñando los
contratos y posteriormente realizar la implementación
• Apiary tiene justamente este valor.
08

10. API BLUEPRINT
Así es como luce un API Blueprint
09

11. API BLUEPRINT
Establecer el nombre de la API
10

12. API BLUEPRINT
API Resource (recurso):
11

13. API BLUEPRINT
Acciones:
12

14. API BLUEPRINT
Mas de una acción->
13

15. API BLUEPRINT
Mas recursos, diferentes formas:
14

16. API BLUEPRINT
Parámetros con Acción:
15

17. API BLUEPRINT
Respuesta sin Body:
16

18. API BLUEPRINT
Múltiples respuestas:
17

19. Mi primer API
18
1. ¿Cómo decidir el nombre?
2. ¿Cómo nombrar a los recursos?
3. ¿Cómo establecer los verbos a
utilizar?
4. ¿Es necesario versionar a las
APIs?

20. SPS Pharma API
19
1. Listado de Sucursales
2. Listado de Sucursal por ID
3. Ubicación de Sucursal por código postal
4. Validación de existencia por medicamento
5. Poner un pedido en una sucursal particular

21. SPS Pharma API Blueprint
20

22. SPS Pharma API Blueprint
Recurso /farmacia
21

23. SPS Pharma API Blueprint
Recurso /farmacia (verbo GET)
22
¿Pero qué le falta?
a)¿Encabezados?
b)¿Respuestas de falla?
c) ¿Códigos de HTTP?

24. SPS Pharma API Blueprint
Recurso /farmacia (GET con un parámetro)
23
Se colocan ejemplos por
cada sucursal.
¿Pero qué aprendimos en láminas
pasadas sobre los parámetros?
¿Cómo lo podemos expresar?

25. SPS Pharma API Blueprint
Recurso /farmacia (GET con un parámetro)
24
Se colocan ejemplos por
cada sucursal.
¿Pero qué aprendimos en láminas
pasadas sobre los parámetros?
¿Cómo lo podemos expresar?

26. SPS Pharma API Blueprint
Recurso /farmacia/cp (GET con un parámetro)
25
Casi es el mismo recurso,
pero hemos agregado /cp.
Con este queremos obtener la
lista de sucursales cercanas a un
código postal.
Falta agregar:
1. Errores
2. Excepciones

27. SPS Pharma API Blueprint
Recurso /farmacia/inventario (GET con un parámetro)
26
Con esto quiero recuperar
la existencia de un medicamento.
¿Qué mas puedo agregar?
¿Encabezados?

28. SPS Pharma API Blueprint
Recurso /farmacia/pedido (POST)
27
Aquí nos faltan igualmente:
1. Errores
2. Excepciones
3. Media Types

29. SPS Pharma API Blueprint
Documentemos bien a nuestra API
28
Vamos a documentar cada recurso.

30. SPS Pharma API Blueprint
Documentemos bien a nuestra API
29
Podemos ir viendo el resultado,
conforme vamos realizando la
Documentación.

31. SPS Pharma API Blueprint
Probemos nuestra API
30
Esta es una gran característica de Apiary. No
únicamente nos sirve para documentar/diseñar a
nuestras APIs, pero también tenemos la capacidad de
probarlas.
Podemos:
a) Probar desde la propia consola de Apiary
b) Copiar el endpoint generado por Apiary y usarlo
desde un navegador o desde Postman, por ejemplo.

32. SPS Pharma API Blueprint
Probando desde la Consola
31
Click sobre el recurso.

33. SPS Pharma API Blueprint
Probando desde la Consola
32
Click sobre este botón.

34. SPS Pharma API Blueprint
Probando desde la Consola
33
Headers.
Después de dar click en el botón, simplemente hacemos scroll down y veremos lo siguiente:

35. SPS Pharma API Blueprint
Probando desde la Consola
34
Justo la respuesta que habíamos
modelado.
Mas abajo vemos:

36. SPS Pharma API Blueprint
Copiando el endpoint
35
Copia y pega esto en un
navegador.
Haz scroll hacia arriba y verás:

37. SPS Pharma API Blueprint
Copiando el endpoint
36
En este caso lo podemos hacer, debido a que
es un GET.

38. SPS Pharma API Blueprint
Probando desde Postman
37
Usemos el recurso
para colocar un pedido.
El request lo copiamos
de nuestra
documentación.
El verbo que usamos
es POST.
Veamos cómo la
respuesta es la que
colocamos.

39. SPS Pharma API Blueprint
Probando desde Postman
38
Modifica la respuesta
desde APIARY y vuelve
a probar el mismo
recurso.
Mira cómo la respuesta
cambia:

40. SPS Pharma API Blueprint
Inspeccionado las llamadas
39
Apiary nos permite realizar una inspección de
nuestras peticiones. Las que están en verde es
porque fueron exitosas con respecto a la
documentación.
Las que están en naranja es que tuvieron un error.

41. SPS Pharma API Blueprint
Inspeccionado las llamadas con algún error
40
¿Por qué nos marcó esto?
En las primeras de llamadas
desde el Postman, ¿qué
content-type hemos
utilizado? ¿Recuerdas?
¿Cuál habíamos colocado
originalmente?

42. SPS Pharma API Blueprint
Integración con GitHub
41
Podemos integrar con
Github para ir realizando los
commits hacia un repositorio
de manera automática.
Así puedes ir promoviendo
tus cambios a tu repositorio
de GitHub.
https://github.com/RCPDevChamp/oracle/blob/master/apiary.apib

43. El rol del desarrollador
43
1. ¿Cómo vivimos actualmente?
2. ¿Gracias a qué podemos habilitar
tantos servicios, APIs y
aplicaciones?
3. ¿Cómo se lleva a cabo la
interoperabilidad de las
aplicaciones?
Además de elementos con igual
importancia como las redes y los
dispositivos, el común denominador
es código.

44. CONTACTO
S&P Solutions
Rolando Carrasco
rcarrasco@spsolutions.com.mx
Twitter: @borland_c
Blog: http://oracleradio.blogspot.com
Web: http://www.spsolutions.com.mx