> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-es/guias-para-colaboradores/api-documentation.md).

# Documentación de la API

Esta página cubre los estándares para documentar APIs usando especificaciones OpenAPI en todos los servicios de Decentraland.

## Objetivos

Nuestro enfoque de documentación de APIs garantiza:

* **Estandarización** - Especificaciones OpenAPI consistentes en todos los servicios
* **Automatización** - Validación, empaquetado y despliegue mediante GitHub Actions
* **Centralización** - Toda la documentación del servicio se publica a través de GitBook
* **Propiedad** - La documentación vive en el repositorio de cada servicio
* **Accesibilidad** - Referencias de API actualizadas y fáciles de usar para los colaboradores

***

## Estructura del repositorio

Cada repositorio de servicio DEBE incluir un `/docs` directorio con la siguiente estructura:

```bash
/docs
  openapi.yaml        # Fuente de verdad (OpenAPI 3.1)
  openapi.json        # Generado automáticamente en CI para Hugo/renderers
  index.html          # Documentación independiente generada automáticamente (opcional)
```

### Requisitos de archivo

#### `openapi.yaml`

* **DEBE** ser el archivo fuente canónico
* **DEBE** usar la especificación OpenAPI 3.1
* **PUEDE** tener un prefijo que identifique el servicio (por ejemplo, `worlds-openapi.yaml`)
* **PUEDE** dividirse en `components/` o `examples/` directorios si es necesario

#### `openapi.json`

* Generado automáticamente durante CI/CD
* Usado por Hugo y otros renderers
* No editar manualmente

#### `index.html`

* Documentación independiente generada automáticamente
* Generada usando Redocly
* Desplegada en GitHub Pages

***

## Estándares OpenAPI

Al escribir `openapi.yaml`, sigue estas convenciones para garantizar coherencia y claridad.

### Resumen del endpoint

**DEBE** debe reflejar la ruta real del endpoint:

```yaml
# ✅ Bien: Ruta de endpoint clara
paths:
  /world/{world_name}/about:
    get:
      summary: /world/{world_name}/about
      description: Recupera información sobre un mundo específico
      
# ❌ Mal: Resumen genérico
paths:
  /world/{world_name}/about:
    get:
      summary: Obtener información del mundo
```

### ID de operación

**DEBE** incluye el nombre del servicio para una unicidad global:

```yaml
# ✅ Bien: ID de operación con prefijo del servicio
operationId: worldsContentServer_getWorldAbout

# ✅ Bien: Otro ejemplo
operationId: socialService_getFriends

# ❌ Mal: Genérico, podría entrar en conflicto
operationId: getAbout
```

**Convención de nombres**: `{serviceName}_{operationDescription}`

* Usar camelCase
* Ser descriptivo pero conciso
* Incluir el contexto del método HTTP cuando sea útil (por ejemplo, `createUser`, `deleteParcel`)

### Versionado

**DEBE** usar versionado semántico (`MAJOR.MINOR.PATCH`) en `info.version`:

```yaml
openapi: 3.1.0
info:
  title: API del servidor de contenido de Worlds
  version: 1.2.0  # Versionado semántico
  description: API para gestionar Worlds de Decentraland
```

**Reglas para incrementar la versión**:

* **MAJOR**: Cambios incompatibles (cambios de API incompatibles)
* **MINOR**: Nueva funcionalidad (compatible con versiones anteriores)
* **PATCH**: Correcciones de errores (compatible con versiones anteriores)

### Etiquetas y agrupación

**DEBE** usar etiquetas para agrupar endpoints relacionados:

```yaml
tags:
  - name: Worlds
    description: Operaciones de gestión de Worlds
  - name: Deployments
    description: Operaciones de despliegue de Worlds
  - name: Health
    description: Endpoints de comprobación de estado

paths:
  /worlds:
    get:
      tags:
        - Worlds
      summary: /worlds
      operationId: worldsContentServer_listWorlds
      
  /worlds/{world_name}/about:
    get:
      tags:
        - Worlds
      summary: /worlds/{world_name}/about
      operationId: worldsContentServer_getWorldAbout
```

{% hint style="info" %}
Las operaciones se agrupan por etiqueta en la navegación de GitBook. Agrupa los endpoints relacionados bajo la misma etiqueta para una mejor organización.
{% endhint %}

### Ejemplo completo

```yaml
openapi: 3.1.0
info:
  title: API del servicio social
  version: 2.1.0
  description: API para gestionar interacciones sociales en Decentraland
  contact:
    name: Colaboradores de Decentraland
    url: https://decentraland.org

servers:
  - url: https://social.decentraland.org
    description: Servidor de producción
  - url: https://social.decentraland.zone
    description: Servidor de staging

tags:
  - name: Friends
    description: Gestión de amigos
  - name: Blocked Users
    description: Operaciones de bloqueo de usuarios

paths:
  /friends:
    get:
      tags:
        - Friends
      summary: /friends
      operationId: socialService_getFriends
      description: Devuelve una lista de los amigos del usuario autenticado
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Respuesta exitosa
          content:
            application/json:
              schema:
                type: object
                properties:
                  friends:
                    type: array
                    items:
                      $ref: '#/components/schemas/Friend'
        '401':
          description: No autorizado

components:
  schemas:
    Friend:
      type: object
      required:
        - address
        - createdAt
      properties:
        address:
          type: string
          description: Dirección Ethereum del amigo
        createdAt:
          type: string
          format: date-time
          description: Cuándo se estableció la amistad
```

***

## Desarrollo local

### Previsualizar la documentación localmente

Usa Redocly CLI para previsualizar tu documentación OpenAPI:

```bash
# Generar documentación HTML
yarn redocly build-docs docs/openapi.yaml -o docs/index.html

# Luego abre docs/index.html en tu navegador
```

### Añadir a package.json

Añade un script de compilación por conveniencia:

```json
{
  "scripts": {
    "build:api": "redocly bundle docs/openapi.yaml -o docs/openapi.json --ext json && redocly build-docs docs/openapi.yaml -o docs/index.html",
    "preview:api": "redocly preview-docs docs/openapi.yaml"
  }
}
```

### Instalar Redocly CLI

```bash
# Usando npm
npm install -g @redocly/cli

# Usando yarn
yarn global add @redocly/cli
```

### Validar la especificación OpenAPI

```bash
# Valida tu especificación
redocly lint docs/openapi.yaml

# Empaqueta y valida
redocly bundle docs/openapi.yaml
```

***

## Configuración de automatización

### Paso 1: Configura los secretos de GitBook

Para publicar las especificaciones de API en GitBook, añade estos secretos a tu repositorio:

**Configuración → Secretos y variables → Actions → Nuevo secreto del repositorio**

| Nombre del secreto        | Descripción                         | Dónde encontrarlo                       |
| ------------------------- | ----------------------------------- | --------------------------------------- |
| `GITBOOK_ORGANIZATION_ID` | El ID de tu organización de GitBook | Configuración de GitBook → Organización |
| `GITBOOK_TOKEN`           | Token de la API de GitBook          | Configuración de GitBook → API Tokens   |

{% hint style="warning" %}
Estos secretos DEBEN configurarse para que el flujo de trabajo automatizado publique en GitBook.
{% endhint %}

### Paso 2: Añade el flujo de trabajo de GitHub Actions

Crear `.github/workflows/build-api-docs.yml` en tu repositorio:

```yaml
name: build-app-docs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
  pull_request:
    paths:
      - 'docs/**'

jobs:
  build:
    uses: decentraland/platform-actions/.github/workflows/apps-docs.yml@main
    with:
      api-spec-file: 'docs/openapi.yaml'
      output-file: 'docs/index.html'
      output-directory: './docs'
      api-spec-name: '{service-name}-api'  # p. ej., 'social-service-api'
      node-version: '20'
    secrets: inherit
```

**Parámetros**:

* `api-spec-file`: Ruta a tu especificación OpenAPI (normalmente `docs/openapi.yaml`)
* `output-file`: Dónde generar la documentación HTML
* `output-directory`: Directorio para los archivos de salida
* `api-spec-name`: Nombre único para tu especificación de API (usado en GitBook)
* `node-version`: Versión de Node.js a usar

**Este flujo de trabajo hará lo siguiente:**:

1. ✅ Validar la especificación OpenAPI
2. ✅ Empaquetar la especificación en un solo archivo
3. ✅ Generar documentación HTML estática usando Redocly
4. ✅ Desplegar automáticamente en GitHub Pages
5. ✅ Publicar la especificación en GitBook (si los secretos están configurados)

### Paso 3: Habilita GitHub Pages

Configura GitHub Pages en tu repositorio:

1. Ve a **Configuración → Pages**
2. En **Compilación y despliegue**:
   * Establece **Source** en **GitHub Actions**
3. Asegúrate de que exista un entorno llamado **github-pages**
4. Guarda los ajustes

Después de la primera ejecución exitosa del flujo de trabajo, tu documentación estará disponible en:

* **Documentación HTML**: `https://decentraland.github.io/<repo>/index.html`
* **Especificación OpenAPI**: `https://decentraland.github.io/<repo>/openapi.yaml`
* **JSON empaquetado**: `https://decentraland.github.io/<repo>/openapi.json`

{% hint style="success" %}
Estas URL seguirán siendo válidas mientras exista el repositorio y GitHub Pages esté habilitado.
{% endhint %}

***

## Añadir a GitBook

Una vez desplegada tu documentación de API, añádela a la documentación centralizada de GitBook.

### Adición manual (proceso actual)

1. Navega al espacio de GitBook
2. Ve a la **Referencia de API** sección
3. Haz clic en **Añadir referencia de API**
4. Introduce los detalles de tu servicio:
   * **Nombre**: El nombre de tu servicio (p. ej., "Social Service")
   * **URL de OpenAPI**: `https://decentraland.github.io/{repo-name}/openapi.yaml`
5. Guardar

### Características de la integración con GitBook

GitBook hará automáticamente lo siguiente:

* Analizar tu especificación OpenAPI
* Generar documentación interactiva de API
* Crear navegación de endpoints basada en etiquetas
* Proporcionar la funcionalidad "Try it"
* Mantener la documentación sincronizada cuando actualices la especificación

***

## Flujo de configuración completo

### Configuración inicial

```mermaid
graph TD
    A[Crear /docs/openapi.yaml] --> B[Añadir flujo de trabajo de GitHub Actions]
    B --> C[Configurar secretos de GitBook]
    C --> D[Habilitar GitHub Pages]
    D --> E[Hacer push a la rama main]
    E --> F[El flujo de trabajo se ejecuta automáticamente]
    F --> G[La documentación se despliega en GitHub Pages]
    G --> H[Añadir manualmente a GitBook]
```

### Actualizaciones continuas

```mermaid
graph LR
    A[Actualizar openapi.yaml] --> B[Crear PR]
    B --> C[El flujo de trabajo valida]
    C --> D[Hacer merge en main]
    D --> E[Despliegue automático en GitHub Pages]
    E --> F[GitBook se sincroniza automáticamente]
```

***

## Buenas prácticas

### Calidad de la documentación

* **Sé descriptivo**: Escribe resúmenes y descripciones claras
* **Proporciona ejemplos**: Incluye ejemplos de solicitud/respuesta
* **Documenta los errores**: Describe todas las posibles respuestas de error
* **Usa Components**: Reutiliza esquemas mediante `$ref` para evitar duplicación
* **Añade descripciones**: Cada parámetro, propiedad y respuesta debe tener una descripción

### Ejemplo con buenas prácticas

```yaml
paths:
  /users/{address}/friends:
    get:
      tags:
        - Friends
      resumen: /users/{address}/friends
      operationId: socialService_getUserFriends
      description: |
        Recupera una lista paginada de amigos para el usuario especificado.
        Devuelve las direcciones de los amigos y metadatos, incluido cuándo se estableció la amistad.
      parameters:
        - name: address
          in: path
          required: true
          descripción: Dirección Ethereum del usuario (con prefijo 0x)
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
          example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: limit
          in: query
          descripción: Número máximo de amigos a devolver (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          descripción: Número de amigos a omitir para la paginación
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          descripción: Lista de amigos recuperada correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FriendsResponse'
              example:
                friends:
                  - address: '0xabcdef...'
                    createdAt: '2024-01-15T10:30:00Z'
                total: 42
                offset: 0
                limit: 50
        '400':
          descripción: Formato de dirección no válido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Formato de dirección no válido'
                code: 'INVALID_ADDRESS'
        '404':
          descripción: Usuario no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
```

### Reutilización de esquemas

```yaml
components:
  schemas:
    Error:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          descripción: Mensaje de error legible para humanos
        code:
          type: string
          descripción: Código de error legible por máquina
        details:
          type: object
          descripción: Contexto adicional del error
          
    PaginatedResponse:
      type: object
      required:
        - offset
        - limit
        - total
      properties:
        offset:
          type: integer
          descripción: Número de elementos omitidos
        limit:
          type: integer
          descripción: Máximo de elementos por página
        total:
          type: integer
          descripción: Número total de elementos disponibles
```

### Esquemas de seguridad

```yaml
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      descripción: Token JWT obtenido desde el endpoint de autenticación

security:
  - BearerAuth: []
```

***

## Validación y comprobaciones de calidad

### Validación pre-commit

Añade un hook pre-commit o una comprobación de CI:

```yaml
# .github/workflows/validate-api-spec.yml
name: Validate API Spec

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm install -g @redocly/cli
      - run: redocly lint docs/openapi.yaml
```

### Reglas comunes de validación

* Todas las rutas tienen operation IDs
* Todas las operaciones tienen tags
* Todos los parámetros tienen descripciones
* Todas las respuestas están documentadas
* Se proporcionan ejemplos
* Los esquemas están referenciados correctamente

***

## Solución de problemas

### El workflow falla

**Problema**: El workflow de GitHub Actions falla

**Soluciones**:

* Revisa los logs del workflow para encontrar errores de validación
* Ejecuta `redocly lint docs/openapi.yaml` localmente
* Verifica las rutas de archivo en la configuración del workflow
* Asegúrate de que los secrets estén configurados correctamente

### GitHub Pages no funciona

**Problema**: Los docs no aparecen en la URL de GitHub Pages

**Soluciones**:

* Verifica que GitHub Pages esté habilitado en la configuración del repositorio
* Comprueba que el workflow se haya completado correctamente
* Espera unos minutos para que GitHub Pages se actualice
* Verifica que el `github-pages` environment exista

### GitBook no se sincroniza

**Problema**: GitBook no muestra los API docs actualizados

**Soluciones**:

* Verifica que los secrets de GitBook sean correctos
* Comprueba que la URL de OpenAPI sea accesible
* Activa manualmente una actualización en GitBook
* Verifica que el spec de OpenAPI sea válido

***

## Migración desde docs existentes

Si ya tienes documentación de API existente:

1. **Exportar a OpenAPI**: Convierte la documentación existente al formato OpenAPI 3.1
2. **Validar**: Usa `redocly lint` para garantizar el cumplimiento
3. **Añadir workflow**: Configura la automatización con GitHub Actions
4. **Probar**: Verifica que los docs se construyan y se desplieguen correctamente
5. **Actualizar enlaces**: Dirige los enlaces de la documentación antigua a la nueva URL de GitHub Pages
6. **Archivar docs antiguos**: Conserva los docs antiguos como referencia durante la transición

***

## Próximos pasos

* Revisa los [Componentes bien conocidos](https://github.com/decentraland/docs/tree/main/contributor/contributor-guides/well-known-components/README.md) estándares para la implementación de API
* Ver [Estándares de prueba](/contributor/contributor-es/guias-para-colaboradores/testing-standards.md) para las guías de pruebas de API
* Consulta ejemplos existentes de API en los [Referencia de API](https://docs.decentraland.org) sección

## Estándares relacionados

* [Gestión de dependencias](/contributor/contributor-es/guias-para-colaboradores/dependency-management.md) - Gestión de dependencias npm y peerDependencies
* [Componentes bien conocidos](https://github.com/decentraland/docs/tree/main/contributor/contributor-guides/well-known-components/README.md) - Arquitectura WKC para servicios
* [Estándares de prueba](/contributor/contributor-es/guias-para-colaboradores/testing-standards.md) - Patrones de prueba para servicios

## Recursos

* **Especificación OpenAPI**: [spec.openapis.org](https://spec.openapis.org/oas/latest.html)
* **Redocly CLI**: [redocly.com/docs/cli](https://redocly.com/docs/cli/)
* **Integración de API de GitBook**: [docs.gitbook.com](https://docs.gitbook.com)
* **Repositorio de Platform Actions**: [github.com/decentraland/platform-actions](https://github.com/decentraland/platform-actions)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/contributor/contributor-es/guias-para-colaboradores/api-documentation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.