API OWNER

Escuela de APIs
Todos los derechos reservados.
Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Transformación digital

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 ¿Qué es la transformación digital?

La transformación digital es la reinvención

de una organización a través de la utilización
de la tecnología digital.

Todos los derechos reservados. Síguenos en @apiaddicts

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 ¿Qué es la transformación digital?

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Nuevos negocios digitales ➢ El corte inglés
➢ Media Market
➢ BBVA
➢ Movistar
➢ Uber ➢ Zara
➢ AirBnb ➢ A3MEDIA
➢ Cabify ➢ Serhos
➢ Netflix
➢ Amazon
Los negocios tradicionales
están cambiando

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 ¿Qué papel juegan las Apis?

Debemos de entender la importancia de las APIs

no por su componente técnico.
La API Economy ha permitido que tengamos un
conjunto de operaciones bien descritas y
catalogadas de forma fácil y sencilla.
Por lo tanto, ha permitido que las funcionalidades
de las empresas sean utilizadas por otras empresas
y así desarrollar una economía digital por capas
(similar a la industrial del automóvil cuando
pasaron de construir los coches una sola marca a
utilizar componentes de otras marcas)

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 ¿Qué es una API?

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 ¿Qué es una API?

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 ¿Qué es una API?

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Algunos datos..
❏ El tráfico a través de las APIs crece un 300% cada año.
❏ El 83% de las peticiones que se realizan por internet se realizan a
través de las APIs.
❏ El mercado de las APIs crece un 30% al año.
❏ El explosivo crecimiento se basa en dos factores:
■ Las organizaciones están adoptando las APis como un canal
más
■ Regulatorio

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 ¿Qué es una API?

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 ¿Qué es una API?

Una APi es una implementación de

un contrato de definición
normalmente definido en un lenguaje
de definición (openapi 3.0 o swagger)
y que se suele exponer en un api
manager

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Developer friendly

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 ¿Qué es ser developer friendly?
Muchas veces decimos o hablamos de que una cosa u otra es
developer friendly, pero, ¿qué es ser developer friendly de verdad?

Debemos pensar que los developers no dejamos de ser usuarios de

herramientas, de programas o de APIs, y que deben cumplir los
principios de usabilidad, como cualquier otra.
Por ello, es importante conocer los principios de usabilidad que
aplican a los developers a la hora de consumir las APIs. A
continuación se enumeran y definen dichos principios:

● Facilidad de aprendizaje
● Flexibilidad
● Robustez

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Facilidad de aprendizaje
Si una API se parece a un estándar de mercado que el developer ya
haya usado, le va a ser más fácil de utilizar. También si todas las
APIs de una organización se parecen, puesto que una vez utilizada
una no tendrá que volverse a aprender el formato.
Además, una de las cosas más complejas es la seguridad. Si la API
utiliza estándar de mercado puede facilitar esta parte.

Para APIs complejas es mejor proporcionar a los developers SDKs,

que ayuden a su integración. Y por supuesto, una buena
documentación de la API, enriquecida con ejemplos y una
herramienta de try-out, ayudan al developer.

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Facilidad de aprendizaje

A menudo nos encontramos con APIs muy

poco flexibles, que devuelven una gran
cantidad de datos y con pocos niveles de
datos de respuesta. Esto hace que, en
ocasiones, el consumidor tenga que
implementarse un backend para poder
agrupar esta información.

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Robustez
La mayor parte de las APIs no están bien probadas. No se han
probado todos los códigos de error, ya sea por falta de tiempo o
bien porque no estaban definidos en ninguna parte.
Testear bien una API, con los formatos de entrada / salida, códigos
de respuesta, rangos de valores.. es importantísimo para que a un
developer le de confianza.

Para esto es aconsejable utilizar herramientas como

Openapi2postman, que te permite generar el conjunto mínimo de
pruebas.

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Conceptos generales

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 APIs internas

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Apis externas

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Consumidores y proveedores

● Consumidores: Son los sistemas

que utilizan la API. Pueden ser
desde servidores, aplicaciones
móviles, webs.
● Proveedores: Son los sistemas que
proveen las operaciones. Pueden
ser otras APIs como micro
servicios, servicios de bus
empresarial, aplicaciones
monolíticas.

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Formatos

El formato preferido para intercambiar datos de una API

es json, aunque también se pueden intercambiar otros
tipos, como xml…

{name: “marco”, surname:

“sanz”,addresses:
[{calle:”velasco”,numero:
”2”},{calle:”capellanes”,
numero:”8”}]

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Lenguaje de definición
openapi: '3.0.0'
info:
version: 'v1'
title: api-template
servers:
- url: https://pre-api.cloudappi.net/api-template/v1

Tradicionalmente se utilizaba documentos

description: Development server
- name: Account types
description: 'Operations and resources related to account types'

para describir las APIs, pero actualmente

paths:
/patients:
x-apigen-binding:

utilizamos lenguajes de definición, dónde el model: Patient

get:
summary: get all patiens for hospital
más utilizado es openapi. El lenguaje de operationId: getPatients
tags:
- Patients
definición nos permite describir los recursos, parameters:
- $ref: "#/components/parameters/init_param"

las operaciones, definir los esquemas,

- $ref: "#/components/parameters/limit_param"
- $ref: "#/components/parameters/total_param"
- $ref: "#/components/parameters/select_param"

ejemplos…
- $ref: "#/components/parameters/exclude_param"
- $ref: "#/components/parameters/expand_param"
- $ref: "#/components/parameters/order_by_param"
responses:
'206':
description: Ok
content:
application/json:
schema:
$ref: "#/components/schemas/standard_response_patients"
examples:
Ejemplo:
$ref: '#/components/examples/get_patient

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 APIRest

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Protocolo Rest
➢ Requiere un protocolo cliente/servidor sin estado. Todas
las peticiones contienen toda la información necesaria →
HTTP(S).
REST
➢ Operaciones bien definidas: verbos HTTP
➢ Sintaxis universal para identificar cada recurso: URI
➢ Uso de hypermedia. Se puede navegar de un recurso a otro
por medio de enlaces.

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Protocolo Rest- Sesión

REST

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Protocolo Rest- Sin sesión

REST

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Restful

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Definición de Apis
RestFul

El estándar RESTFULL, define cómo se deben realizar las peticiones

REST, cuales son los métodos HTTP que se deben utilizar y cómo deben
estructurarse las uris para que sean user-friendly. Podemos basarnos
en https://github.com/WhiteHouse/api-standards para definir nuestra
API.

Principios básicos:
➢ Una URL identifica un recurso. Por ejemplo, GET
http://testapi.cloudappi.net/users-eee?param-id=xxxx

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Restful
Principios básicos

➢ Uniformidad de interfaz. Los recursos se manipulan a través de las

métodos HTTP (PUT, PATCH, GET, POST AND DELETE).
○ POST crea el recurso
○ PUT permite modificarlo
○ DELETE lo elimina
○ GET permite consultarlo.
○ Adicionalmente, se han introducido nuevos métodos, como
PATCH (actualización parcial de un recurso)
○ OPTIONS

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Restful
➢ Uniformidad de salida. Los códigos HTTP de salida:
○ 1xxx: Informacional
○ 2xx: Resultado satisfactorio
■ 200: OK
■ 201: Recurso creado
■ 202: Aceptado, no procesado
■ 204: No content
■ 206: Partial content
○ 3xx: Redirecciones
○ 4xx: Errores de cliente
■ 400: Parámetros incorrectos
■ 404: recurso no encontrado
■ 401/403: Forbidden
○ 5xx: Errores de servidor
Todos los derechos reservados.
■ total
Se encuentra prohibida la reproducción 500: Error
o parcial interno
de este documento, salvode servidor
autorización expresa del
autor.
 Restful
Principios básicos

➢ Mensajes autodescriptivos: Los recursos están desacoplados de la

representación.
➢ Los mensajes se pueden devolver en varios formatos. Los mensajes se
pueden obtener en una variedad de formatos como HTML, XML, json…
Para indicar estos formatos, se puede utilizar las cabeceras
Content-Type y Accept o bien indicarlo al final de la URI. Por ejemplo:
GET testapi.cloudsystems.es/users.json
➢ Todas las peticiones son sin estado

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Buenas prácticas

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Buenas prácticas
Consideraciones generales
➢ Paginación por clave valor tanto para base de datos operaciones y no
operaciones (parámetro limit / offset): Se debe mostrar un offset y el
número de elementos a devolver.
GET
/clients?$limit=100&$init=WWSS-222-22&orderby=level&desc=true$tot
al=true
➢ Paginación por página: Se debe mostrar el número de página y el
tamaño de la misma
GET /clients?$page=2&page_size=200

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Buenas prácticas
Consideraciones generales

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Buenas prácticas
Paginación:
Tenemos 1,5 millones de usuarios y la API no tiene ordenación.
Queremos obtener un listado ordenador por surname decreciente y no es
la ordenación de la API por defecto.
¿Cuántas páginas tenemos que retornar?
page_size: 20
num_pages: 75.000 páginas
num_requests: 75.000 requests

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Buenas prácticas
$expand
➢ Atributos con 2 niveles: ¿Qué hacemos con la información
relacionada?
➢ 2 opciones:
- opción1: devolvemos los coches siempre con los usuarios.
- opción2: no devolvemos los coches, deben preguntar a la API de coches siempre.
- opción3: creamos un atributo especial, $expand
GET /users$expand=coches&coches.color=red
[{name:222,surname:222,age:22,coches:{XXX:XX,X:XX,X:XX,X:XX},
{name:222,surname:222,age:22,coches:{XXX:XX,X:XX,X:XX,X:XX}]

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Buenas prácticas
$expand
➢ Atributos con 2 niveles: Si una petición devuelve una lista de
elementos de 2 niveles se debe poder seleccionar si se quiere o no
devolver la información de segundo nivel.

GET /users?$expand=coches
[{name:222,surname:222,age:22,coches:{XXX:XX,X:XX,X:XX,X:XX},
{name:222,surname:222,age:22,coches:{XXX:XX,X:XX,X:XX,X:XX}]

user. {name:222,surname:222,age:22,address:{XXX:XX,X:XX,X:XX,X:XX}

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Buenas prácticas
$select
Si tenemos GET https://api.cloudappi.net/clients

50 atributos
1 atributos es de tipo base 64 imagen 5MB media
1000 elementos
¿qué ocurre un listado de todos mis clientes?

GET https://api.cloudappi.net/clients?$select=name,surname,age
user:[ {name:222,surname:222,age:22}]

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Buenas prácticas
$filter
Permite indicar los criterios de búsqueda. La definición del formato y la
implementación son complejas.
Parámetros
¿Qué significa
GETespeciales
/users?name=”Marco” & firstname=”Sanz”?

¿Qué significa
GET /users?name=”M” & firstname=”S”? ¿AND o OR?

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Buenas prácticas
$filter

/users?$filter={like:{name:”M”}}
Parámetros
/users?$filter={name:{in:[“marco”,”Juan”]}}
especiales
Se utiliza el lenguaje de filtrado de MongoDB

/users?$filter={$or[$like["name","m"],$like["name","s"]}

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Buenas prácticas
Métodos no controlados
➢Clientes con métodos limitados: Algunos clientes de la API pueden
no soportar realizar las peticiones POST, DELETE, GET y PUT.
➢pj: delete /users?dni=22333
requestBody: NO PUEDE TENER

POST /users/delete?DNI=47041896L
POST /users/get
body: {dni:47041896L}
GET /users
user. {name:222,surname:222,age:22,address:{XXX:XX,X:XX,X:XX,X:XX}

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Parámetros especiales
Resumen

● $expand: permite expandir un subelemento.

● $orderBy: indica el criterio de ordenación de los resultados de una
consulta. Puede ser un array con varios criterios.
orderby=name,surname&asc=true,false
● $select: permite seleccionar qué atributos de una entidad queremos
recuperar.
● $filter: permite indicar los criterios de búsqueda. La definición del
formato y la implementación son complejas.

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 CRUD

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Restful
Ejemplo
Crear un usuario
POST http://apitest.cloudappi.net/users
body:
{"name": "Marco", "firstname": "Polo", "lastname": "2",
"address": { "descripcion": "blab bla", "number": "2" }}
resultado:
Header:
HTTP CODE: 400 bad parameters
Body:
{”errors”:[{code:1001,description:”nombre incorrecto”}] },
"data": { "id": "23" }
}
Todos los derechos reservados.
Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor. ”1001”: “Nombre incorrecto, por favor revisa que tenga XXX
 Restful
Ejemplo

Obtener usuarios:
GET http://apitest.cloudsystems.es/users?$limit=100
resultado:
Header: HTTP CODE: 200
Body:
{ “data": [
{ "name": "Marco","firstname": "Polo",
"address": {"descripcion": "blabbla"}},
{ "name": "Prueba","firstname": "ww",
"address": {"descripcion": "blab bla" }}]
}}

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Restful
Ejemplo

Actualizar un usuario
PUT/PATCH http://apitest.cloudsystems.es/users/23
body:
{lastname:”González”}
resultado:
Header:
HTTP CODE: 200
Body:
{“data”:{ "name": "Marco","lastname": " González",
"address": {"descripcion": "blabbla"}} }
}

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Restful
Ejemplo

Eliminar un usuario
DELETE http://apitest.cloudsystems.es/users/47041896L
resultado:
Header:
HTTP CODE: 200
Body:
{“data”:{ "name": "Marco","lastname": " González",
"address": {"descripcion": "blabbla"}} }
}

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Formatos
➢ Se recomienda JSON, aunque no se desaconseja
el uso de otros estándares.
➢ Excepciones: archivos
➢ Especificar siempre las cabeceras:
■ Accept
■ Content-Type
■ Accept-Language

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Formatos
➢ Cuidar los formatos de parámetros numéricos y fechas:
○ Utilizar tipos numéricos si es posible.
○ Para cantidades monetarias añadir siempre la divisa
➢ Las fechas deben seguir un estándar. Se recomienda ISO 8601
updated=”20200108T161805Z”
UTC / GMT ??
➢ Especificar siempre la diferencia horaria.

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Práctica
Ejercicio

● Definamos una API. ● Requisitos :

● ¿Qué necesitamos? ● Al menos un recurso
● Definir el CRUD completo:
● Un portátil con acceso a internet. ● GET (un elemento de la colección)
● Recordar todo lo que podamos de lo que ● GET (toda la colección)
acabamos de ver. ● POST
● Ganas de aprender. ● PUT o PATCH
● DELETE

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Práctica:
Ejercicio Happy new year

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Práctica:
Ejercicio Solución

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 DDD

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 DDD- Principios

❏ Ubiquitous Language

❏ Bounded Context

❏ Domain Model

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 OpenAPI 3

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 ¿Qué es? ¿Para qué sirve?
❖ Es una de las especificaciones para definir APIs REST más
ampliamente utilizadas

❖ Permite generar y visualizar la documentación de la API en un

lenguaje “natural”

❖ Hace posible publicar la API directamente en diversas

herramientas de API management

❖ Se integra muy bien con herramientas de desarrollo mediante

plugins y extensiones

❖ Hace posible la generación de mock servers

❖ Es compatible con muchas herramientas que hacen más ágil

y sencillo el desarrollo
Todos los derechos reservados.
Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Estructura básica (información general)
❖ openapi* ➔ Versión OpenAPI del documento

❖ info* ➔ Información básica de la API:

◆ version*: Versión de la API como tal
◆ title*: Nombre de la API
◆ description
◆ license
◆ termsOfService
◆ contact: datos de contacto del responsable
● name
● url
● email

❖ servers* ➔ Listado de servidores:

◆ url*: URL Del servidor
◆ description: breve descripción. Útil para, por ejemplo, indicar el entorno
al que corresponde el servidor y algún otro detalle relevante.

❖ tags ➔ Listado de etiquetas que podemos utilizar

para organizar los endpoints de nuestra
API:
◆ name*: nombre de la etiqueta
* campos requeridos ◆ description: breve descripción del propósito de la etiqueta

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Estructura básica (secciones principales)

❖ paths* ➔ Sección donde se definen los recursos.

Indicaremos solamente el path posterior a
la url base. Por ejemplo, /customers. Bajo
cada path se definen las operaciones que
admite. Cada una de ellas incluye varias
subsecciones, siendo las más importantes:
◆ parameters
◆ requestBodies
◆ responses*

❖ components ➔ Sección donde se incluyen todas las

definiciones reutilizables.

* campos requeridos

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 paths
❖ path + operación = endpoint.

❖ Las operaciones posibles se corresponden

con los verbos HTTP: GET, POST, PUT, PATCH
y DELETE. Por cada una que definamos, se
generará un endpoint.

❖ Cada uno de los endpoints, a su vez, tendrá

sus propias subsecciones, a saber:
summary, operationId, description,
parameters, requestBodies, responses...

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Operaciones en paths (estructura)
❖ Información general: ❖ Parameters: array de parámetros propios:
➢ summary: brevísima descripción de la ➢ name*: nombre único.
finalidad del endpoint. ➢ in*: ubicación: query, header o path.
➢ description: descripción detallada del ➢ required: indica si es obligatorio.
endpoint. ➢ description: descripción de
➢ operationId: identificador de la funcionalidad. Es recomendable
operación completarlo.
➢ tags: etiquetas asignadas. Pueden ➢ schema*: esquema o modelo del
utilizarse una, varias o ninguna. parámetro.

➔ Cuando son comunes, conviene

definirlos en la sección
components.parameters y referenciarlos.
➔ No es necesario incluir las cabeceras
Accept, Content-Type y Authorization,
pues serán ignoradas.
* campos requeridos

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Operaciones en paths (estructura)

➔ RequestBodies: se utilizan en operaciones ➔ Cuando son comunes, conviene

POST, PUT y PATCH. Definen la información definirlos en la sección
que debe enviarse en el body de la petición: components.requestBodies y
description: breve descripción referenciarlos.
required: indica si es obligatorio
content*: definición por media_type de ➔ Pueden especificarse varios. Esto nos
respuesta (JSON, XML, etc.) permite definir varios formatos de
<media_type> (deben ser acordes a la respuesta, de posibles respuestas,
RFC 6838): etc.
schema : definición directa o
referenciada del cuerpo

* campos requeridos

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Operaciones en paths (estructura)
❖ Responses: Se deben incluir todas las ➔ content*:
posibles respuestas del endpoint. Es un <media_type>
mapa clave-valor, conformado por cada schema*: esquema de la respuesta
código http de respuesta (clave) y la para el media_type especificado.
definición de su contenido (valor): Puede definirse aquí o referenciarse.
❖ Las respuestas comunes pueden definirse example: ejemplo único de respuesta
en el apartado components.responses y examples: lista de ejemplos de
referenciarse. respuesta. Cada uno de ellos lleva su
❖ Los ejemplos de la subsección examples propio nombre y valor. Este apartado
pueden definirse en el apartado es clave en la generación de mock
components.examples y referenciarse. servers. Tanto estos ejemplos como
➢ description: breve descripción los anteriores deben ajustarse al
➢ headers: cabeceras de la respuesta schema de la respuesta.
(pueden ser referenciadas)

* campos requeridos

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Components

❖ Almacén de datos donde se definen todos ❖ Schemas: contiene modelos de cualquier

los modelos reutilizables o referenciables. tipo. Pueden utilizarse para componer
Lo que no se vaya a reutilizar o no tenga modelos más complejos.
sentido definir aquí, deberá definirse en el
propio lugar en el que se utilice. Está ❖ Parameters: contiene parámetros comunes
compuesto por estas subsecciones: a varios endpoints. Es un mapa clave-valor.
schemas
➢
➢ parameters Se definen de igual modo que en paths.
➢ requestBodies
➢ headers
➢ responses ❖ RequestBodies: contiene cuerpos de
➢ examples
➢ securitySchemes petición reutilizables. Es un mapa
links
➢
➢ callbacks clave-valor. Se definen igual que en paths.

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Components
❖ Headers: similar a parameters. Está ❖ SecuritySchemes: contiene los esquemas
orientado a almacenar las cabeceras de de autorización definidos para el control de
respuesta comunes. De nuevo, se trata de acceso a la API. Admite varios flujos:
un mapa clave-valor. ➢ HTTP Basic, Bearer y otros
➢ API keys, ya sea en query string,
❖ Responses: Mapa clave-valor de respuestas cabeceras o cookies
reutilizables. Se definen del mismo modo ➢ Oauth2
que en paths. Si especificamos ejemplos, ➢ OpenID Connect Discovery
serán utilizados en todos los lugares donde
se referencie la respuesta. ➔ Se aplican a nivel de API o de endpoint
mediante el apartado security, donde se
❖ Examples: almacén de ejemplos de los referencian uno o varios de los flujos
modelos. Referenciables desde cualquier definidos en securitySchemes. Si se hace
sección que contenga ejemplos. A veces se a nivel de endpoint se sobreescribe lo
reutilizan, pero en este caso no es indicado a nivel de API.
frecuente. Está orientado a hacer más
sencilla y limpia la definición y su lectura.
Todos los derechos reservados.
Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 schemas
❖ Sección utilizada para definir todo tipo de
modelos. Por cada modelo, se define:

➢ description: breve descripción.

➢ type*: tipo del esquema. Puede ser
primitivo (integer, number, boolean,
string), un array o un objeto (object).
➢ properties: cada una de las propiedades
del objeto. A su vez, estas también son
modelos.
➢ required: array que indica si alguna de
las properties es obligatoria.
➢ example.
➢ example

* campos requeridos

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Modificadores ➢ Cadenas:
■ pattern: expresión regular que debe
cumplirse.
❖ En la definición de modelos, pueden ■ maxLength: longitud máxima.
utilizarse modificadores para indicar ■ minLength: longitud mínima.
determinadas restricciones. ■ format: hay diversos formatos
➢ Generales: posibles (date, date-time, password,
enum: indica un rango de byte y binary)
valores discretos de ➢ Numéricos:
cualquier tipo. ■ maximum: valor máximo
default: valor por defecto, en ■ minimum: valor mínimo
caso de no indicarse ■ format: indica el tipo equivalente
ninguno. ● Integer:
nullable: indica si la ◆ format: int32 → integer
propiedad puede adquirir ◆ format: int64 → long
valor nulo. ● number:
◆ format: float
◆ format: double
* campos requeridos

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Referencias y composición
❖ Es posible referenciar todo tipo de modelos ❖ La composición, se basa en definir modelos con
previamente definidos. Las principales propiedades básicas que sirvan como base para
características de esta posibilidad son: construir otros más complejos. Se puede partir de
➢ Sintaxis: $ref: ‘<ubicación>’. las propiedades básicas y añadir otras nuevas.
Por ejemplo: $ref: ➢ Los modificadores utilizados para realizar esta
‘#/components/<sección>/model’. En composición son:
este caso, sección podría ser schemas, ■ oneOf: valida que el valor recibido sea
responses, etc. según aplique. exactamente igual al de uno de los esquemas
➢ Podemos referenciar modelos de la referenciados.
sección components, ubicados en ■ allOf: valida el valor contra todos los
archivos externos o ubicados en URLs esquemas referenciados.
externas. ■ anyOf: valida el valor contra cualquiera de
➢ Es posible referenciar respuestas, las propiedades de los esquemas
parámetros, otros modelos, etc. pero no referenciados. Admite cualquier
podremos referenciar en la sección info o combinación posible.
directamente bajo paths. ➢ Ejemplo sintaxis:
allOf:
Todos los derechos reservados. - $ref: ‘<ubicación del modelo>’
Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor. - $ref: …
 Práctica

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Práctica

https://apiquality.es/

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Práctica: solución

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.
 Preguntas

Todos los derechos reservados.

Se encuentra prohibida la reproducción total o parcial de este documento, salvo autorización expresa del
autor.