Documentación técnica de APIs, MongoDB, JSON Schema y Microservicios

Definición y Estructura de OpenAPI

openapi: 3.0.0
info:
  title: API
  version: 1.0.0

paths:
  /recurso/{id}:
    parameters:
      - $ref: "#/components/parameters/ID"
    get:
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Recurso"
        "404":
          description: Not found

  /recurso:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Recurso"
      responses:
        "201":
          description: Created
        "400":
          description: Invalid input

components:
  parameters:
    ID:
      name: id
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/ID"

  schemas:    Recurso:     type: object    required:  - name        properties: id:    $ref: "#/components/schemas/ID"    name:        type: string    ID      type: string

Metadatos de Libros

 Dune & Messiah

Consultas en MongoDB

1) Película con más premios wins:
db.movies.find(
  { "awards.wins": { $ne: null } },
  { _id: 0, title: 1, "awards.wins": 1 }
).sort({ "awards.wins": -1 }).limit(1)

2) Clasificaciones rated y número, de más a menos:
db.movies.aggregate([
  { $group: { _id: "$rated", total: { $sum: 1 } } },
  { $sort: { total: -1 } }
])

3) Géneros diferentes:
Si piden número por género:
db.movies.aggregate([
  { $unwind: "$genres" },
  { $group: { _id: "$genres", total: { $sum: 1 } } },
  { $sort: { total: -1 } }
])

4) Películas entre 1970 y 1985 incluidos:
db.movies.countDocuments({
  year: { $gte: 1970, $lte: 1985 }
})

Si piden listado:
db.movies.find(
  { year: { $gte: 1970, $lte: 1985 } },
  { _id: 0, title: 1, year: 1 }

Esquema JSON (JSON Schema)

{
  "type": "object",
  "additionalProperties": false,
  "required": ["userId", "username", "email", "role", "orders"],
  "properties": {
    "userId": {
      "type": "string",
      "pattern": "^USR-[0-9]{5}$"
    },
    "username": {
      "type": "string",
      "minLength": 4,
      "maxLength": 16
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "role": {
      "type": "string",
      "enum": ["admin", "editor", "customer"]
    },
    "orders": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["orderId", "status", "total"],
        "properties": {
          "orderId": {
            "type": "string",
            "pattern": "^ORD-[0-9]{4}$"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "paid", "cancelled"]
          },
          "total": {
            "type": "number",
            "exclusiveMinimum": 0
          }

Conceptos Clave de Desarrollo Backend y Arquitectura

API: interfaz para usar funciones/datos. Servicio web: API accesible por red, normalmente HTTP. REST: estilo arquitectural orientado a recursos. Recurso: entidad con URI (/books/1). Stateless: cada petición trae toda la información; el servidor no recuerda la sesión. HATEOAS: respuestas con enlaces para navegar. application/json: media type JSON.

Métodos HTTP: GET leer | POST crear | PUT reemplazar | PATCH modificar parcial | DELETE borrar.

JSON: formato ligero de intercambio. Bien formado = sintaxis correcta. Válido = cumple el schema. Reglas JSON: claves con "", strings con "", sin comentarios, sin coma final, true/false/null en minúscula.

XML: lenguaje de marcado autodescriptivo. XML bien formado: raíz única, etiquetas cerradas, las mayúsculas importan, atributos con comillas, escapar & como &, < como <. Prolog opcional pero si está va al principio.

NoSQL: base de datos no relacional. MongoDB = NoSQL documental, documentos tipo JSON/BSON. Tipos NoSQL: document, key-value, wide-column, graph.

ACID: Atomicity = todo o nada | Consistency = mantiene la validez | Isolation = las transacciones no interfieren | Durability = lo confirmado queda guardado.

CAP: Consistency = último dato o error | Availability = respuesta no errónea | Partition tolerance = funciona con fallos de red. Con partición no se pueden garantizar C y A perfectas a la vez.

BASE: Basic availability = disponible ante fallos | Soft state = el estado puede cambiar | Eventual consistency = acaba siendo consistente.

Microservicios: SOA con servicios pequeños desplegables independientemente. Alta cohesión = el servicio hace cosas relacionadas. Bajo acoplamiento = los servicios dependen poco entre sí.

Ventajas de los microservicios: escalado independiente, despliegue independiente, equipos autónomos, tecnologías distintas por servicio. Desventajas: más complejidad, fallos de red, testing difícil, monitorización difícil, consistencia de datos difícil.

Tipos de acoplamiento: implementation = comparten detalles internos (muy malo) | temporal = deben estar disponibles a la vez | deployment = hay que desplegar juntos | domain = dependencia por reglas del dominio.