Este documento presenta OpenAPI 3.0.2 como estándar para documentar APIs de forma interoperable. Explica cómo OpenAPI puede usarse para documentar APIs existentes, definir contratos de API antes de implementarlas, o generar documentación a partir de servicios existentes. También cubre herramientas de OpenAPI, casos de uso comunes, y tendencias como la adopción del estándar por gobiernos y empresas para promover la interoperabilidad.

1. Diseño de API
con OpenAPI 3.0.2

2. Pedro J. Molina
@pmolinam
https://metadev.pro

3. OpenAPI Initiative https://www.openapis.org

4. https://www.linuxfoundation.org

5. Miembros

6. Grupo de Investigación ISA
Promoviendo un estándar para SLAs en APIs:
https://github.com/isa-group/SLA4OAI-Specification

7. Grupo de Investigación ISA

8. API
 Servicio para que otros los
consuman
 Descripción técnica (orientado a
devs)
 Promueve la interoperación de
sistemas mediante contratos claros
y perdurables en el tiempo
Application Programmer Interface

9. API
API como contrato para servicios y clientes

10. APIs agnósticas de lenguaje
1. CORBA >> C + IDL
2. SOA >> XML + SOAP + WDSL …
3. REST >> JSON + HTTP

11. Breve Historia
 2011.09 Swagger 1.0
 2015.03 SmartBear compra Swagger
 2016.01 SmartBear dona Swagger a Linux Fund.
 2016.01 OpenAPI 2.0 / Linux Foundation
 2017.07 OpenAPI 3.0
 2018.10 OpenAPI 3.0.2

13. OpenAPI Initiative
 Herramientas
 Editor http://editor.swagger.io
 Explorador de APIs http://petstore.swagger.io
 Validador https://online.swagger.io/validator
 Generadores opensource para
 skeletons para backends
 proxies para clientes o front-end
 http://swagger.io/swagger-codegen

14. Casos de uso
1. API Legada
2. Contrato primero
3. Dirigida por el servicio

15. 1. API Legada
 Documentar un API existente
 Construcción del contrato
http://editor.swagger.io
 Validación
 Resultados:
 API documentada
 Generación de SDKs para cliente
API

16. 1. API Legada. Ejemplo
¿Es Nieves un nombre de hombre o de mujer?
Servicio web para descubrirlo
http://www.jerolba.com/mujeres-y-hombres-y-serverless
GET https://us-central1-hombre-o-mujer.cloudfunctions.net/gender?name=nieves
Créditos: Jerónimo López @jerolba
API

17. openapi: ‘3.0.2'
info:
version: "1.0.1"
title: Hombre o mujer.
tags:
- name: Gender
description: API para género for frecuencia estadística.
1. API Legada. Contrato API
http://bit.ly/gender-openapi3

18. paths:
/gender:
get:
description: |
Devuelve la probabilidad de que el nombre sea de mujer u hombre.
parameters:
- name: name
in: query
description: Nombre de la persona
required: true
schema:
type: string
responses:
# Response code
‘200’:
description: Respuesta con exito
content:
application/json:
schema:
$ref: ‘#/definitions/GenderResponse’
1. API Legada. Contrato API
'404':
description: Not found
content:
application/json:
schema:
$ref:
'#/components/schemas/GenderNotFoundResponse'

19. totalMale:
type: number
format: int32
totalFemale:
type: number
format: int32
GenderNotFoundResponse:
required:
- name
- gender
properties:
name:
type: string
gender:
type: string
components:
schemas:
GenderResponse:
required:
- name
- gender
- probability
- totalMale
- totalFemale
properties:
name:
type: string
gender:
type: string
probability:
type: number
format: float
1. API Legada. Contrato API

20. 2. Contrato Primero
 La especificación se escribe en primer lugar
http://editor.swagger.io
 Puede generarse:
 un skeleton para el backend
 Un proxy o SDK para el cliente
 Permite paralelizar el trabajo en backend y frontend.
 Los cambios al contrato pueden versionarse
adecuadamente.
API Cliente

21. 2. Contrato Primero. Servidores disponibles

22. 2. Contrato Primero. Clientes disponibles

23. 3. Dirigida por el servicio
 El servicio define el contrato
 La especificación del API en formato OpenAPI se genera por
una librería que hace reflexión sobre el servicio.
 Requiere cuidado para no romper la compatibilidad del API.
 Ejemplo: https://openapi3.herokuapp.com
 Fuente: https://github.com/pjmolina/event-backend
API Cliente

24. API ManagementTools

25. API ManagementTools
 Aportar una capa que se
coloca por delante del API
 Gestionada por 3ºs
 Aporta:
 Autenticación, Autorización
 Seguridad basada en roles
 Protección frente a ataques DOS
 Monetización: cobro por
 Escalado
 Auditoría
 Métricas de uso, analíticas
Ejemplos
 3scale
 Apigee
 Mashape Kong
 CA 7Layers
 Azure API Management
 IBM Bluemix API
Management
 WSO

26. Escalabilidad en APIs
 API sin estado
 Con un balanceador de carga
en el frontal (como p.e.
nginx o ha-proxy)
 Que distribuye el trafico a N
(con N>=2) servidores
 DNS, SSL y certificados se
configuran solo en el
balanceador
api
lb api
api
#0
#1
#2
443
80

27. Librerías para usar OpenAPI hoy
 Prototipado
 oas-tools / oas-generator (OpenAPI 3.0) https://www.npmjs.com/package/oas-
generator
 swagger-tools (OpenAPI 2.0) https://www.npmjs.com/package/swagger-tools
 Directorios de Herramientas
 https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md
 https://openapi.tools/
 https://github.com/metadevpro/openapi3-ts
 Conversión de contratos 2.0 a 3.0
 Mermade https://mermade.org.uk/openapi-converter

28. Estandarización de APIs
 Gobierno de Holanda
 Estandarizo OpenAPI 3.0 a nivel nacional (2018.05) https://www.linkedin.com/pulse/why-
dutch-government-standardised-openapi-3x-dimitri-van-hees/
 Gobierno de Canadá, British Columbia
https://catalogue.data.gov.bc.ca/group/bc-government-api-registry
 En estudio por la Comisión Europea. Considerando estandarizarlo en toda la
UE.
 eBay publica todas su APIs en formato OpenAPI 3.0
 Stripe https://github.com/stripe/openapi
 AWS

29. OpenAPI, la Banca y Fintech
 Directiva Europea PSD2
 Directiva para Pagos Digitales
 Mercado Único de Pagos en la UE
 Servicios de iniciación de Pagos (PIS)
 Servicios de información de cuenta (AIS)
https://www.bbva.com/es/lo-saber-la-psd2/
https://www.swift.com/news-events/press-
releases/swift-creates-financial-sector-api-
blueprint

30. OpenAPI Roadmap
 JSON Schema
 Overlays
 Firmado y encriptado de peticiones: JOSE
 Más métodos de Autenticación (Certs, OAuth2 scopes)
 Multisegment Paths
 Message based API
 Roadmap para 3.1:
https://github.com/OAI/OpenAPI-Specification/issues/1466

31. CAL Profile
 CAL Profile https://github.com/metadevpro/cal
 Se aceptan contribuciones (Issues, Pull Requests, etc.)
 Recomendaciones para APIs REST sobre OpenAPI
 Implementaciones de Referencia
 NodeJS + TypeScript https://github.com/metadevpro/alba-node
 dotNet Core https://github.com/metadevpro/alba-netcore

32. Conclusiones
OpenAPI:
 definir
 consumir
 publicar
 documentar
 y gestionar APIs interoperables

33. ¡Gracias!
@pmolinam