API, REST, JSON, OpenAPI y documentación interactiva

Antes de empezar#

En la unidad anterior construimos el vocabulario de una conversación HTTP: un cliente dirige una petición a un recurso y un servidor devuelve una respuesta. Ahora añadiremos una segunda capa de comprensión. Una aplicación no expone mensajes aislados al azar; ofrece una interfaz con operaciones, datos y resultados que otros programas deben poder entender de forma estable.

En esta conversación aparecen varias palabras que suelen mezclarse: API, REST, JSON, OpenAPI, Swagger UI y ReDoc. Están relacionadas, pero pertenecen a categorías diferentes. Confundirlas conduce a frases como «mi JSON es REST» o «Swagger es la API», que ocultan qué parte del sistema se está describiendo.

Conocimientos previos. Debes poder leer una URL, una petición, una respuesta, un método y un código de estado. También conviene recordar las propiedades safe e idempotent estudiadas en la Unidad 1.1.

Mapa conceptual. Seguiremos este recorrido:

1. Una API define una interfaz y un contrato observable entre proveedor y consumidor.
2. En una API orientada a recursos distinguimos el recurso de sus representaciones y de las entidades internas que lo implementan.
3. REST aporta restricciones arquitectónicas; no es un formato de datos ni un sinónimo de CRUD.
4. JSON permite serializar valores estructurados como texto intercambiable.
5. OpenAPI describe formalmente operaciones HTTP, entradas, respuestas y schemas.
6. Swagger UI y ReDoc consumen esa descripción y la presentan a personas.

1. API web y contrato entre sistemas#

Interfaz, proveedor y consumidor#

Una API (Application Programming Interface) es una interfaz mediante la cual un componente de software ofrece capacidades a otros componentes. La idea es más amplia que la Web: una biblioteca de Python, un sistema operativo y una base de datos también pueden exponer APIs. En este curso nos concentraremos en APIs web, cuyos consumidores se comunican con un proveedor mediante mensajes HTTP.

El proveedor implementa y publica la interfaz. El consumidor programa contra ella: puede ser una aplicación web, una aplicación móvil, un proceso de integración, una prueba automatizada u otro servicio. Estos papeles no describen empresas ni máquinas fijas. Un servicio puede proveer una API a un frontend y consumir a su vez la API de un sistema de pagos.

La interfaz marca una frontera. El consumidor no necesita conocer las funciones internas, las tablas ni el lenguaje del proveedor. Necesita saber qué mensajes puede enviar y cómo interpretar los resultados. Esa separación permite que ambos lados evolucionen de manera independiente mientras conserven el acuerdo observable.

El contrato no se limita a la sintaxis. Dos respuestas pueden contener JSON válido y aun así no respetar el acuerdo: quizá falta un campo obligatorio, un importe usa otra unidad o un 200 OK encubre un rechazo. La forma y el significado deben mantenerse alineados.

Mapa mínimo de una operación#

Antes de escribir código, una operación sencilla puede describirse mediante cinco preguntas:

• Recurso: ¿qué concepto se consulta o modifica?
• Método y ruta: ¿qué semántica HTTP y qué identificador se utilizan?
• Entrada: ¿qué parámetros, cabeceras o representación debe aportar el consumidor?
• Salida satisfactoria: ¿qué código, cabeceras y representación recibirá?
• Resultados alternativos: ¿qué rechazos o fallos forman parte del contrato?

Una API suele contener muchas operaciones relacionadas. Un endpoint se usa coloquialmente para señalar un punto de acceso concreto, a menudo la combinación de método y ruta. Por eso GET /libros/42 y DELETE /libros/42 comparten la ruta, pero representan operaciones distintas del contrato.

Compatibilidad y evolución#

Un consumidor incorpora supuestos sobre lo que observa. Si el proveedor cambia una ruta, elimina un campo, altera el tipo de un valor o redefine un código, ese consumidor puede dejar de funcionar aunque el servidor continúe respondiendo.

Un cambio compatible conserva las expectativas existentes o añade posibilidades que los consumidores pueden ignorar de forma segura. Un cambio incompatible obliga a adaptar a los consumidores. La clasificación concreta depende del contrato: añadir un campo suele ser tolerable para un cliente flexible, pero puede romper a otro que rechace propiedades desconocidas.

2. Recursos, entidades y representaciones#

El recurso es el concepto identificable#

En REST, un recurso es aquello que puede identificarse y convertirse en objetivo de una interacción: un libro concreto, la colección de libros, el estado de un pedido o el informe vigente. La definición original de Fielding subraya que el recurso es una asociación conceptual, no el valor puntual que exista en un instante.

La ruta /libros/42 puede conservar su identidad aunque cambien el título corregido, la disponibilidad o la representación devuelta. El identificador señala el concepto «libro 42»; no congela todos sus valores.

Representación no equivale a entidad interna#

Una representación es la forma transferible mediante la que se comunica el estado actual o pretendido de un recurso. Puede ser JSON, HTML, una imagen u otro tipo de contenido. El Content-Type describe el tipo de la representación que viaja en el mensaje.

Una entidad interna es una estructura propia de la implementación: una fila, un objeto del dominio o un documento almacenado. Puede participar en la construcción de la respuesta, pero no cruza la red como objeto vivo. Se transforma en bytes siguiendo un formato.

3. REST como estilo arquitectónico#

REST (Representational State Transfer) es un estilo arquitectónico definido mediante restricciones. No es un protocolo alternativo a HTTP, una biblioteca de Python, un esquema de URL ni un formato de archivo. Una API puede utilizar HTTP y JSON sin satisfacer de manera completa las restricciones REST.

Restricciones esenciales#

La interfaz uniforme es central. Fielding la descompone en identificación de recursos, manipulación mediante representaciones, mensajes autodescriptivos e hipermedia como motor del estado de la aplicación. En este nivel nos concentraremos en las tres primeras para diseñar y leer contratos sencillos.

La restricción stateless recupera una idea de la Unidad 1.1, pero en REST es más exigente: el servidor comprende cada petición sin depender de contexto de sesión almacenado entre peticiones. Esto no impide que existan recursos persistentes ni que una credencial viaje en cada mensaje; distingue el estado del recurso del contexto de sesión de la interacción.

CRUD es una correspondencia frecuente, no la definición de REST#

CRUD resume cuatro capacidades de persistencia: crear, leer, actualizar y eliminar. Es posible relacionarlas con métodos HTTP, pero esa tabla no agota REST ni sustituye la semántica del protocolo.

Una API necesita además búsquedas, transiciones, cálculos o procesos que no encajan limpiamente en cuatro verbos de almacenamiento. Forzar toda operación a parecer CRUD puede ocultar la intención. El diseño debe identificar primero el concepto estable que el consumidor necesita manipular.

4. Diseño básico de rutas y operaciones#

Colecciones, elementos y nombres consistentes#

Una convención útil es representar colecciones mediante un nombre plural y elementos mediante un segmento identificador:

• /libros identifica la colección.
• /libros/42 identifica un elemento.
• /autores/7/libros puede identificar la colección de libros relacionada con un autor cuando esa relación aporta una frontera clara.

El método expresa la semántica general y la ruta identifica el recurso. Esto favorece combinaciones previsibles como GET /libros, POST /libros y GET /libros/42.

Los sustantivos son una guía, no una prueba automática de calidad. Una transición de negocio como cancelar un pedido podría exponerse mediante un recurso subordinado —por ejemplo, POST /pedidos/42/cancelaciones— o mediante una operación explícita bien documentada. Lo importante es que el contrato haga visible la intención, conserve la semántica HTTP y no finja una actualización genérica cuando existe una regla de transición propia.

PUT frente a PATCH#

PUT /libros/42 expresa normalmente que la representación enviada define el estado pretendido del recurso completo en esa URI. Repetir la misma petición conserva el mismo efecto pretendido; por eso PUT es idempotent.

PATCH /libros/42 describe una modificación parcial. Su cuerpo necesita un formato y una semántica explícitos: no basta con decir «envío algunos campos». Omitir un campo, enviarlo como null y asignarle un valor son intenciones distintas que el contrato debe separar. PATCH puede diseñarse de forma idempotent, pero HTTP no le atribuye esa propiedad automáticamente.

5. JSON y representación de datos#

JSON (JavaScript Object Notation) es un formato textual, ligero e independiente del lenguaje para serializar datos estructurados. La norma RFC 8259 define cuatro tipos primitivos —string, number, boolean y null— y dos tipos estructurados —object y array—.

{
  "id": 42,
  "titulo": "Redes para aplicaciones",
  "disponible": true,
  "etiquetas": ["http", "arquitectura"],
  "edicion": null,
  "autor": {
    "id": 7,
    "nombre": "Ada Torres"
  }
}

En este texto aparecen todos los tipos fundamentales:

• El valor completo es un object, una colección de pares nombre-valor entre llaves.
• etiquetas contiene un array, una secuencia ordenada entre corchetes.
• titulo y nombre son strings entre comillas dobles.
• id es un number.
• disponible es un boolean escrito en minúsculas.
• edicion es null, un valor explícito que representa ausencia de valor dentro del documento.

JSON no es un diccionario de Python#

Un diccionario de Python es un objeto que vive en la memoria de un proceso. Un documento JSON es texto que respeta una gramática. Se parecen visualmente, pero no son intercambiables sin transformación.

El recorrido conceptual de una respuesta puede expresarse así:

objeto interno → valores compatibles → texto JSON → bytes HTTP
bytes HTTP → texto JSON → análisis sintáctico → valores del consumidor

En HTTP, Content-Type: application/json declara que el cuerpo contiene una representación JSON. No garantiza que el documento cumpla el contrato de negocio; solo identifica el media type que debe utilizar el receptor para interpretarlo.

HTTP/1.1 200 OK
Content-Type: application/json

{"id":42,"titulo":"Redes para aplicaciones","disponible":true}

Límites y tipos que necesitan una convención#

JSON no tiene tipos nativos para fechas, horas, UUID, valores decimales exactos, bytes o enumeraciones. Esos conceptos deben proyectarse a tipos JSON y acompañarse de una regla semántica. Una fecha puede viajar como string —por ejemplo, "2026-07-23"—, pero el string por sí solo no explica el formato ni la zona temporal.

También conviene distinguir campo ausente y campo con null. En el primer caso el nombre no aparece; en el segundo aparece con un valor explícito. La consecuencia exacta se definirá en el contrato y se ampliará al estudiar Pydantic y actualizaciones parciales.

Errores de JSON frecuentes#

• Usar comillas simples: {'titulo': 'HTTP'} parece Python, pero no es JSON válido.
• Escribir True, False o None en lugar de true, false y null.
• Añadir una coma después del último miembro o elemento.
• Incluir comentarios, que no forman parte de la gramática JSON estándar.
• Repetir nombres dentro de un objeto. RFC 8259 recomienda nombres únicos porque los parsers divergen ante duplicados.
• Enviar NaN o Infinity, valores que la gramática JSON no permite.

6. OpenAPI como descripción formal#

OpenAPI Specification define una interfaz estándar e independiente del lenguaje para describir APIs HTTP. Un documento OpenAPI permite que personas y herramientas descubran las capacidades publicadas sin leer el código fuente ni deducir el contrato observando tráfico.

FastAPI genera este documento a partir de la aplicación declarada. La documentación oficial actual muestra openapi: 3.1.0 en /openapi.json; por eso esta unidad utiliza la terminología de OpenAPI 3.1. La especificación OpenAPI más reciente puede avanzar de versión sin que eso cambie automáticamente la versión emitida por el framework.

Mapa de un documento OpenAPI#

OpenAPI usa la palabra schema en dos escalas. El documento completo describe el contrato de la API. Dentro de él, los Schema Objects describen la forma de datos concretos. FastAPI relacionará posteriormente esos schemas de datos con tipos de Python y modelos Pydantic.

Lectura de un documento mínimo#

El siguiente fragmento describe, no implementa, la consulta de un libro:

openapi: 3.1.0
info:
  title: Biblioteca API
  version: 1.0.0
paths:
  /libros/{libro_id}:
    get:
      summary: Consultar un libro
      parameters:
        - name: libro_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Libro encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Libro"
        "404":
          description: Libro no encontrado
components:
  schemas:
    Libro:
      type: object
      required: [id, titulo, disponible]
      properties:
        id:
          type: integer
        titulo:
          type: string
        disponible:
          type: boolean

La lectura se realiza de fuera hacia dentro:

1. openapi selecciona el vocabulario 3.1.
2. info identifica el contrato y su versión declarada.
3. paths contiene /libros/{libro_id}.
4. Bajo esa ruta, get define la operación HTTP.
5. parameters declara que libro_id está en el path, es obligatorio y debe ser entero positivo.
6. responses documenta al menos los resultados 200 y 404.
7. La respuesta 200 anuncia contenido application/json y reutiliza el schema Libro mediante $ref.

requestBody no aparece porque esta lectura no necesita cuerpo. En una operación de creación o actualización, el documento podría describir allí los media types aceptados y sus schemas.

La descripción no ejecuta la API#

El documento OpenAPI es una representación procesable del contrato, no el servidor. Puede existir aunque la implementación esté detenida, y puede quedar desactualizado si se mantiene manualmente sin disciplina. Del mismo modo, una operación documentada no demuestra que sus reglas estén implementadas correctamente.

OpenAPI puede alimentar documentación, pruebas, validadores y generación de clientes. Esta unidad solo desarrolla la lectura del contrato y su visualización; JSON Schema avanzado y generación de SDKs quedan fuera de alcance.

7. Swagger UI, ReDoc y rutas documentales#

FastAPI utiliza el documento OpenAPI generado como fuente para dos interfaces incluidas por defecto:

Las tres rutas son configurables. La documentación oficial de FastAPI permite cambiar openapi_url, docs_url y redoc_url, o desactivar estas salidas. Si se desactiva el documento OpenAPI, también dejan de funcionar las UIs que dependen de él.

La documentación es una vista del contrato#

El flujo conceptual de FastAPI será:

tipos y declaraciones de la aplicación
            ↓
documento OpenAPI en /openapi.json
            ↓
Swagger UI en /docs  ·  ReDoc en /redoc  ·  otras herramientas

Este automatismo reduce trabajo repetitivo y ayuda a mantener sincronizada la documentación estructural. No sustituye decisiones claras. Un nombre ambiguo, una ruta incoherente o un error no declarado seguirán siendo ambiguos aunque se representen con una interfaz elegante.

Los metadatos —título, resumen, descripción, versión, contacto, licencia y tags— mejoran la lectura y organización. Se introducirán en contexto cuando creemos la primera aplicación FastAPI. Aquí basta con reconocer que forman parte de la descripción pública y deben hablar del contrato, no de detalles internos irrelevantes.

8. Ejemplo integrado: de una necesidad a la documentación#

Supongamos que una aplicación lectora necesita consultar la ficha pública de un libro. Todavía no escribiremos un servidor; seguiremos la información que debería existir en el contrato.

Paso 1. Identificar recurso y consumidor#

El consumidor es la aplicación lectora y el proveedor es el servicio de biblioteca. El recurso es «el libro identificado por 42», no la fila interna ni el JSON. La ruta /libros/42 mantiene esa identidad aunque la representación cambie.

Paso 2. Definir la operación HTTP#

La intención es leer, por lo que se selecciona GET. El mapa contractual queda así:

GET /libros/42 HTTP/1.1
Host: api.example.test
Accept: application/json

Paso 3. Representar el resultado#

El proveedor transforma datos internos en una representación pública. El contrato no expone claves de almacenamiento ni información privada del autor.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "titulo": "Redes para aplicaciones",
  "disponible": true
}

El cuerpo es JSON; no es «la API». La API es el conjunto de operaciones y reglas que permite obtener esta y otras representaciones.

Paso 4. Localizar la operación en OpenAPI#

En el documento se busca primero paths, después /libros/{libro_id} y finalmente get. Dentro de esa operación se localizan el parámetro de path y las respuestas. El schema Libro explica la estructura del JSON satisfactorio.

Swagger UI transformará esos elementos en una operación desplegable con un control para libro_id, una lista de respuestas y una vista del schema. ReDoc presentará la misma información con otra organización visual. Cambia la vista, no el contrato fuente.

Paso 5. Verificar la coherencia#

La revisión conceptual comprueba que:

• La ruta identifica un recurso y el método comunica lectura.
• El parámetro real coincide con el declarado en OpenAPI.
• El Content-Type coincide con la representación JSON.
• Los códigos documentados coinciden con los resultados que el consumidor debe manejar.
• El schema describe los campos publicados, no la estructura completa de almacenamiento.
• Swagger UI y ReDoc muestran la misma fuente OpenAPI, aunque la presenten de manera diferente.

9. Errores conceptuales frecuentes#

10. Síntesis final#

Una API establece una frontera programable entre un proveedor y sus consumidores. Su contrato explica qué operaciones existen, qué información aceptan y cómo comunican resultados. En una API orientada a recursos, los identificadores señalan conceptos estables y las representaciones transportan su estado sin exponer necesariamente la implementación interna.

REST organiza una arquitectura mediante restricciones como client-server, stateless, cache, uniform interface y layered system. No equivale a HTTP, JSON ni CRUD. Las rutas y métodos coherentes son una parte visible de esa organización, pero no su definición completa.

JSON serializa un conjunto pequeño de tipos como texto. Un programa debe convertir entre estructuras internas y esa representación; tipos como fechas o UUID necesitan convenciones adicionales. application/json identifica el formato, no garantiza el cumplimiento del contrato.

OpenAPI convierte el contrato HTTP en una descripción procesable. FastAPI la publicará por defecto en /openapi.json; Swagger UI y ReDoc utilizarán esa misma fuente para ofrecer vistas distintas. La automatización ayuda a sincronizar estructura y documentación, pero la claridad sigue dependiendo de las decisiones del diseñador.

Vocabulario esencial: API, proveedor, consumidor, contrato, endpoint, recurso, entidad interna, representación, REST, uniform interface, stateless, JSON, serialización, deserialización, OpenAPI Document, Operation Object, Parameter Object, Request Body Object, Responses Object, Schema Object, Swagger UI y ReDoc.

Después de estudiar esta unidad deberías poder:

• Explicar por qué API, REST, JSON y OpenAPI pertenecen a categorías distintas.
• Separar un recurso de su almacenamiento y de su representación.
• Reconocer rutas y métodos coherentes en un caso sencillo sin reducir REST a CRUD.
• Identificar tipos válidos y errores frecuentes de JSON.
• Recorrer un documento OpenAPI desde paths hasta parámetros, respuestas y schemas.
• Explicar por qué /docs y /redoc son vistas del contrato publicado en /openapi.json.

Fuentes#

• FastAPI — First Steps

  Secciones Interactive API docs, Alternative API docs, OpenAPI, API schema, Data schema y Check the openapi.json: generación de OpenAPI 3.1.0 y relación con Swagger UI y ReDoc.

• Roy T. Fielding — Architectural Styles and the Design of Network-based Software Architectures, capítulo 5

  Secciones 5.1.2 Client-Server, 5.1.3 Stateless, 5.1.5 Uniform Interface, 5.1.6 Layered System, 5.2.1.1 Resources and Resource Identifiers y 5.2.1.2 Representations. Fuente complementaria necesaria porque la documentación de FastAPI usa REST como contexto, pero no define el estilo.

• FastAPI — Metadata and Docs URLs

  Secciones Metadata for API, OpenAPI URL y Docs URLs: metadatos, /openapi.json, /docs, /redoc y opciones para configurarlos o desactivarlos.

• OpenAPI Initiative — OpenAPI Specification 3.1.0

  Introducción y secciones OpenAPI Document, Paths Object, Operation Object, Parameter Object, Request Body Object, Responses Object y Schema Object. Referencia normativa para no confundir el documento con sus UIs.

• IETF — RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format

  Secciones 1 a 7 y 11: formato textual, tipos, objetos, arrays, strings, números, literales y media type application/json. Fuente complementaria necesaria porque las fuentes principales no detallan la gramática y los límites de JSON.

• FastAPI Beyond CRUD — Chapter 16: API Documentation

  Secciones OpenAPI Specification, Swagger, Customizing the API Metadata y Redoc. Se utiliza como continuidad práctica; las rutas y el comportamiento actual se contrastaron con la documentación oficial de FastAPI.