Este documento describe las APIs y los protocolos webservices SOAP y REST. Explica que una API describe funcionalidades independientemente de su implementación y permite la comunicación entre aplicaciones y procesos. También describe herramientas como Swagger que permiten documentar APIs RESTful y recomendaciones para diseñar buenas APIs REST como usar códigos de estado HTTP, versionar la API, usar recursos y paginación.

1. Documentando APIs
Ezequiel Gonzalez Rial
gonrial@gmail.com
@gonrial DevSpark

2. Que es una API?
Interfaz de Programación de Aplicaciones
Describe funcionalidades
independientemente de su implementación
Ejemplos:
– Aplicación ↔ Librería.
– Ente 2 procesos en ejecución (dependen del SO)
– Procesos que corren entre distintas máquinas

3. Webservices
• Servicios que se comunican usando usando
internet
• Primeros intentos de web services: SOAP 1998
• Deriva de un protocolo creado por Dave Winer
en 1998, llamado XML-RPC.
• SOAP fue creado por Microsoft, IBM y otros.
Está actualmente bajo el auspicio de la W3C,
mantenido por el XML Protocol Working Group.

4. El crecimiento y caída de
SOAP / WSDL / UDDI
• XML hasta en la SOPA!!!! (cuac)
• 1998: SOAP (Simple Object Access Protocol) es un
protocolo estándar que define cómo dos objetos en
diferentes procesos pueden comunicarse por medio de
intercambio de datos XML.
• 2000: WSDL (Web Services Description Language), un
formato XML que se utiliza para describir servicios Web.
• 2000: UDDI (Universal Description, Discovery and
Integration) permite registrar y buscar servicios en un
catálogo: Páginas blancas, Páginas amarillas, Páginas
verdes.

5. REST al rescate
• Representational State Transfer
• Primera vez que se lo nombra Defensa de
Tesis de Doctorado, Roy Fielding, 2000
• Ayudante de Tim Berners-Lee escribiendo la
especificación de HTTP/1.1
• Recomendable para leer!

6. Características de una API-REST
• Basado en HTTP
• Interfase Uniforme
• Recursos
• Manipulación de recursos a través de representaciones
• Mensajes auto-descriptivos
• HATEOAS: Hypermedia as the Engine of Application State
• Sin-estado
• Cacheable
• Sistema de Capas

7. Herramientas para documentar
API-REST
Swagger

8. Swagger
• Una especificación y un framework que permite
describir, producir, consumir y visualizar
servicios RESTful.
• Centrado en la especificación.
• Independiente del lenguaje.
• Librerías para múltiples lenguajes y
generadores de código
– NodeJS usando Express.
• Herramientas de terceros: Apigee-127

9. RESTful API Modeling Language
• Es una especificación y un framework. Permite
describir de forma rápida y simple. Permite el
descubrimiento de endpoints y el reuso de
comportamientos, y pretende que emerjan las
mejores practicas.
• Desarrollado por Mulesoft
• Hosteado (SaaS)
• No tiene un soporte nativo de Nodejs.

10. API Blueprint
• Centrado en el ciclo de vida de una API.
Permite que se discuta la API con otros.
Genera documentación y conjuntos de pruebas
de forma automática.
• Hosteado (SaaS)

11. Postman
• Herramienta que permite inspeccionar APIs y
guarda un historial de consultas.
• Inicialmente extensión de Google Chrome.
• Permite organizar las consultas realizadas y
puede generar un documento resultado.
• Definición de un workflow de trabajo.

12. Recomendaciones
para una buena API-REST
• Usar los códigos de estado de HTTP (rfc2616)
• Versionar la API
– URL (/v1/...) o encabezados
• Usar sustantivos, no verbos
• Usar la forma plural
• GET y HEAD no deben alterar el estado
• Usar recursos anidados

13. Recomendaciones
para una buena API-REST
• Paginar
– Usar query strings
– Las paginas son recursos
– Usar encabezados HTTP (Github)
• Links para HATEOAS
– Custom vendor media type (no escala)
– HAL
– Xlink
– Collections+JSON
• Devolver siempre un mensaje de error consistente

14. Preguntas?
Ezequiel Gonzalez Rial
gonrial@gmail.com
@gonrial

15. Muchas Gracias!