Lista de contenidos

Obtiene una lista de contenidos de un proyecto.

Este endpoint es útil para obtener todos los contenidos o se puede filtrar por un modelo específico. Por ejemplo, si tienes un modelo llamado post, puedes usar un query param para obtener todos los contenidos de ese modelo.

Endpoint

curl https://api.contentisland.net/api/1.0/contents \
--header 'Authorization: Bearer TU_TOKEN_DE_ACCESO'

Query Params

Este endpoint acepta los siguientes query params:

interface ContentListQueryParams {
  id?: ClientFilter<string>;
  contentType?: ClientFilter<string>;
  language?: string;
  `fields.${string}`?: ClientFilter; // Permite filtrar por valores específicos de campos
  // Por ejemplo: 'fields.slug': 'my-post'
  includeRelatedContent?: boolean | number | 'all'; // Cuántos niveles de contenido relacionado expandir. `false` / `0` -> nada; `true` / `1` -> 1 nivel (legacy); `2..15` -> N niveles; `'all'` -> tope (15). Ver "Expansión de contenido relacionado" más abajo.
  pagination?: {
    take?: number; // Número de elementos a recuperar
    skip?: number; // Número de elementos a omitir
  };
  sort?: {
    contentType?: 'asc' | 'desc'; // Ordenar por modelo de contenido en orden ascendente o descendente
    lastUpdate?: 'asc' | 'desc'; // Ordenar por fecha de última actualización
    `fields.${string}`?: 'asc' | 'desc'; // Ordenar por valores específicos de campos
  };
}

nombre	descripción
`id`	El campo `id` del contenido a recuperar. Este filtro es útil cuando se quiere recuperar una lista de contenidos pero se conoce los ids de éstos. Por ejemplo: `/contents?id[in]=1,2,3`
`contentType`	El modelo del contenido que queremos recuperar. Por ejemplo: `/contents?contentType=post`
`language`	El idioma del contenido que queremos recuperar. Cuando aplicamos este filtro, solamente devolverá los campos del modelo en el idioma seleccionado y descartará los demás. Por ejemplo: `/contents?language=es`
`fields.${string}`	Permite filtrar por valores específicos de campos. Ejemplos: `/contents?fields.slug=my-post` `/contents?fields.title[in]=hello%20world,hola%20mundo` Recupera contenidos con campos que coincidan con los valores especificados.
`includeRelatedContent`	Controla cuántos niveles de contenido relacionado expande el servidor en una sola respuesta. Acepta `false`, `true` (1 nivel, legacy), `0..15` o `'all'` (alias del tope de profundidad, 15). Ver la sección Expansión de contenido relacionado para límites, respuestas parciales y cabeceras. Ejemplos: `/contents?includeRelatedContent=true` — 1 nivel (legacy). `/contents?includeRelatedContent=3` — 3 niveles. `/contents?includeRelatedContent=all` — hasta 15 niveles.
`pagination`	Un objeto que permite paginar los resultados. `take`: Número de elementos a recuperar. `skip`: Número de elementos a omitir. Por ejemplo: `client.getContentList({ pagination: { take: 10, skip: 20 } })` recupera 10 elementos omitiendo los primeros 20.
`sort`	Un objeto que permite ordenar los resultados. `contentType`: Ordenar por modelo de contenido en orden ascendente o descendente. `lastUpdate`: Ordenar por fecha de última actualización. `fields.${string}`: Ordenar por valores específicos de campos. Por ejemplo: `client.getContentList({ sort: { 'fields.title': 'asc' } })` ordena por el campo `order` en orden ascendente.

type ClientFilter<Type = string | boolean | number> =
  | Type
  | {
      in?: Type[];
      ne?: Type;
      nin?: Type[];
    };

nombre	descripción
`string`	Filtra el contentido donde el parámetro `es igual` a este valor. Por ejemplo: `/contents?contentType=post` Recupera una lista de contenidos cuyo `modelo es igual a post`
`in`	Filtra el contenido donde el parámetro `contiene alguno` de estos valores. Por ejemplo: `/contents?language[in]=es,en` Recupera una lista de contenidos filtrando los campos que coincidan con `es` y/o `en`
`ne`	Filtra el contenido donde el parámetro `no es igual` a este valor. Por ejemplo: `/contents?contentType[ne]=page` Recupera una lista de contenidos cuyo `modelo no es igual a page`
`nin`	Filtra el contenido donde el parámetro `no contiene ninguno` de estos valores. Por ejemplo: `/contents?contentType[nin]=page,post` Recupera una lista de contenidos cuyo `modelo no sea ni page ni post`

Ejemplo:

// Recupera una lista de contenidos filtrando por el modelo y el idioma
curl https://api.contentisland.net/api/1.0/contents?contentType=post&language[in]=es,en \
--header 'Authorization: Bearer TU_TOKEN_DE_ACCESO'

Respuesta

La respuesta es un array de objetos JSON que contienen información sobre los contenidos. Cada objeto tiene la siguiente estructura:

export interface Content {
  id: string;
  contentType: { id: string; name: string };
  lastUpdate: Date;
  fields: Field[];
}

export interface Field {
  id: string;
  name: string;
  value: any;
  type: FieldType;
  isArray: boolean;
  language: string;
}

id: El ID del contenido.
contentType: El modelo al que pertenece el contenido. Contiene un id y un name.
lastUpdate: La fecha de la última actualización del contenido.
fields: Un array de objetos que representan los campos del contenido.

Ejemplo:

[
  {
    "id": "1",
    "contentType": {
      "id": "100",
      "name": "post"
    },
    "lastUpdate": "2023-10-01T12:00:00Z",
    "fields": [
      {
        "id": "111",
        "name": "title",
        "value": "Hola Mundo",
        "type": "short-text",
        "isArray": false,
        "language": "es"
      },
      {
        "id": "222",
        "name": "body",
        "value": "Este es el cuerpo del post en markdown.",
        "type": "long-text",
        "isArray": false,
        "language": "es"
      },
      { "id": "333", "name": "order", "value": 1, "type": "number", "isArray": false, "language": "es" }
    ]
  }
]

Expansión de contenido relacionado

El query param includeRelatedContent recorre el grafo de contenido relacionado desde cada elemento devuelto hasta N saltos en una sola respuesta.

Valor	Comportamiento
omitido, `false`, `0`	Sin expansión. Los campos relacionados conservan su id como string.
`true` (legacy)	Expande 1 nivel (equivalente a `includeRelatedContent=1`).
`1`, `2`, … `15`	Expande N niveles.
`all`	Alias del tope de profundidad (15).
cualquier otro valor (`foo`, `-1`, `1.5`, `16`, …)	`400 Bad Request` con `{ error: "includeRelatedContent must be one of: false, true, 0..15, all" }`.

Límites

Profundidad máxima: 15. Tope defensivo — los grafos reales raramente exceden 4-5 niveles.
Presupuesto por petición: 500 contenidos resueltos. Si abrir el siguiente nivel superaría 500, el nivel no se abre (corte a nivel entero). Los ids no resueltos siguen como string en el cuerpo de la respuesta.

Respuestas parciales

Toda respuesta incluye:

X-Related-Content-Resolved-Depth: entero, la profundidad realmente alcanzada (0 cuando no hay expansión).
X-Related-Content-Partial: presente y con valor true sólo cuando la respuesta se truncó — por el presupuesto o porque la profundidad pedida se agotó cuando el grafo aún tenía más alcance.

El cuerpo de la respuesta sigue siendo Content[] plano — sin envelope. Para detectar referencias sin resolver, comprueba si un field.value de tipo modelo relacionado es un string id en lugar de un objeto.

Ejemplo con expansión multi-nivel

curl 'https://api.contentisland.net/api/1.0/contents?includeRelatedContent=2' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

HTTP/1.1 200 OK
X-Related-Content-Resolved-Depth: 2

Si el grafo llega a un tercer nivel, la misma llamada devuelve el mismo cuerpo pero añade X-Related-Content-Partial: true.

Ciclos

La expansión deduplica ids globalmente mientras recorre el grafo, así que un ciclo A → B → A con profundidad ≥ 2 carga cada contenido exactamente una vez: B aparece expandido dentro del campo de A, y dentro de B el campo que apunta a A conserva el id de A como string.

Códigos de estado

Código	Descripción
200	La solicitud se ha procesado correctamente y se ha devuelto la información del proyecto.
400	Petición inválida. `includeRelatedContent` está fuera del conjunto de valores aceptados.
401	No autorizado. El token de acceso no es válido o ha expirado.
500	Error interno del servidor. Ocurrió un error al procesar la solicitud.