API Pública de Conteúdo

A API Pública de Conteúdo dá-lhe acesso programático só de leitura aos artigos de blog da sua organização Nolorem. Utilize-a para importar conteúdo para um site Drupal, um front end personalizado, uma aplicação móvel ou qualquer sistema externo que precise dos dados do seu blog.

A API está disponível no plano Premium. Todo o acesso é só de leitura; a publicação e a edição permanecem dentro do Nolorem.

Criar uma Chave de API

Só os administradores da organização podem criar chaves de API.

1. Nas Definições, desloque-se até à secção Chaves de API (visível apenas para administradores).
2. Clique em Criar chave de API.
3. Introduza um nome descritivo para a chave (por exemplo, "Website Drupal" ou "Script de sincronização de conteúdo").
4. Escolha o âmbito da chave (ver abaixo).
5. Copie a chave apresentada no ecrã. Começa por nlr_live_.

A chave é apresentada apenas uma vez. Guarde-a imediatamente num gestor de segredos ou variável de ambiente. Se a perder, revogue a chave e crie uma nova.

Escolher o Âmbito de uma Chave

Ao criar uma chave, escolhe se esta abrange um blog específico ou todos os blogs da sua organização.

Chave delimitada a um blog (recomendado): a chave está associada a um único blog. Só pode aceder a artigos, categorias e etiquetas desse blog. Se a chave for alguma vez divulgada ou partilhada, apenas o conteúdo desse blog fica exposto.

Chave de toda a organização: a chave tem acesso a todos os blogs da sua organização. Utilize-a apenas quando tiver uma razão deliberada para aceder a vários blogs com uma única chave.

O selo de âmbito em cada chave da lista mostra a que blog a chave está associada, ou "Todos os blogs" para uma chave de toda a organização. O âmbito é fixado na criação. Para alterar o âmbito, crie uma nova chave com o âmbito pretendido, atualize os consumidores e depois revogue a chave antiga.

Autenticar Pedidos

Passe a chave no cabeçalho Authorization de cada pedido:

Authorization: Bearer nlr_live_your_key_here

Exemplo com curl:

curl https://nolorem.io/api/v1/posts \
  -H "Authorization: Bearer nlr_live_your_key_here"

A API é servidor-a-servidor. Não existem cabeçalhos CORS, pelo que os clientes de navegador não a podem chamar diretamente. Faça todas as chamadas à API a partir do seu back-end ou de um script do lado do servidor.

Listar os Seus Blogs

GET /api/v1/blogs lista os blogs a que a sua chave pode aceder. A estrutura da resposta é a mesma quer a chave esteja delimitada a um blog quer seja de toda a organização.

curl https://nolorem.io/api/v1/blogs \
  -H "Authorization: Bearer nlr_live_your_key_here"

Resposta:

{
  "data": [
    { "id": "uuid", "slug": "my-blog", "name": "My Blog" },
    { "id": "uuid", "slug": "company-news", "name": "Company News" }
  ]
}

Uma chave delimitada a um blog devolve exatamente uma entrada (o blog associado). Uma chave de toda a organização devolve todos os blogs. Utilize este endpoint para descobrir que blogs uma chave abrange antes de obter conteúdo.

Filtrar Artigos por Blog

Todos os endpoints de conteúdo aceitam um parâmetro blog opcional. Passe o UUID ou o slug do blog:

# Filtrar por slug
curl "https://nolorem.io/api/v1/posts?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Filtrar por UUID
curl "https://nolorem.io/api/v1/posts?blog=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Se omitir blog, a API devolve conteúdo de todos os blogs a que a sua chave pode aceder (o comportamento predefinido, não disruptivo).

Se utilizar uma chave delimitada a um blog e passar ?blog= a apontar para um blog diferente, a API devolve 403 Forbidden. Isto impede adivinhar que blogs existem numa organização.

O mesmo parâmetro blog funciona em /api/v1/categories e /api/v1/tags.

Listar Artigos

GET /api/v1/posts devolve uma lista paginada de artigos dos blogs acessíveis pela sua chave. Por predefinição, devolve artigos publicados, 20 por página.

curl "https://nolorem.io/api/v1/posts?status=published&per_page=50" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Resposta:

{
  "data": [
    {
      "id": "uuid",
      "blog_id": "uuid",
      "title": "My blog post",
      "slug": "my-blog-post",
      "excerpt": "Lead paragraph...",
      "language": "en",
      "category": "Technology",
      "tags": ["AI", "Productivity"],
      "featured_image_url": "https://...",
      "published_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-10T14:30:00Z",
      "html": null
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 123 }
}

O campo html é sempre null nas respostas de lista. Utilize os endpoints de detalhe para obter o corpo completo do artigo.

Filtros Disponíveis

Parâmetro	Descrição	Exemplo
blog	UUID ou slug do blog (predefinição: todos os blogs acessíveis)	blog=my-blog
status	published, draft ou scheduled (predefinição: published)	status=published
language	Código de idioma ISO 639-1	language=nl
category	Nome da categoria (não distingue maiúsculas de minúsculas)	category=Technology
tag	Nome da etiqueta (não distingue maiúsculas de minúsculas)	tag=AI
updated_since	Data e hora ISO 8601; apenas artigos modificados após esta data	updated_since=2026-06-01T00:00:00Z
page	Número da página, a começar em 1	page=2
per_page	Itens por página, máx. 100	per_page=100

Obter um Único Artigo

Obtenha um artigo pelo seu UUID para conseguir o corpo HTML completo:

curl "https://nolorem.io/api/v1/posts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Ou pelo seu slug:

curl "https://nolorem.io/api/v1/posts/slug/my-blog-post" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Ambos devolvem um único objeto PublicPost (não envolvido num array data) com o campo html preenchido.

Sincronização Incremental com updated_since

Para sincronizar apenas conteúdo novo ou alterado, guarde a data e hora da sua última sincronização bem-sucedida e passe-a como updated_since na execução seguinte:

# Sincronização inicial: obter todos os artigos publicados
curl "https://nolorem.io/api/v1/posts?per_page=100" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Sincronizações seguintes: apenas artigos alterados desde a última sincronização
curl "https://nolorem.io/api/v1/posts?updated_since=2026-06-10T14:30:00Z&per_page=100" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Percorra todos os resultados com paginação antes de guardar a nova data e hora de sincronização.

Detetar Artigos Despublicados ou Eliminados

Quando utiliza updated_since para sincronização incremental, a resposta predefinida só devolve artigos que ainda estejam publicados. Se um artigo foi despublicado ou eliminado no Nolorem desde a sua última sincronização, simplesmente desaparece dos resultados, sem qualquer sinal para o remover no destino.

Para obter esse sinal, passe include_deleted=true juntamente com a sua data e hora updated_since:

curl "https://nolorem.io/api/v1/posts?updated_since=2026-06-10T14:30:00Z&include_deleted=true" \
  -H "Authorization: Bearer nlr_live_your_key_here"

A resposta inclui todos os artigos em direto normalmente, mais entradas de lápide mínimas acrescentadas ao final de data. Cada lápide tem:

• id: o UUID do artigo que já tem de uma sincronização anterior
• status: o estado atual do artigo, ou "deleted" se foi removido permanentemente
• updated_at: quando ocorreu a alteração
• deleted: true se o artigo foi eliminado, false se foi apenas despublicado ou movido para rascunho

{
  "data": [
    { "id": "...", "title": "Live post", "updated_at": "..." },
    { "id": "...", "status": "draft", "updated_at": "...", "deleted": false },
    { "id": "...", "status": "deleted", "updated_at": "...", "deleted": true }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 1, "tombstones": 2 }
}

Utilize meta.tombstones para saber quantas entradas de lápide estão acrescentadas. meta.total reflete sempre apenas os artigos em direto.

Quando a sua ferramenta de sincronização vê uma lápide, despublique ou remova a página correspondente no destino (por exemplo, defina o nó Drupal correspondente como despublicado ou rascunho).

Sem include_deleted=true, o comportamento é idêntico ao anterior a esta alteração: só são devolvidos os artigos publicados em direto.

Listar Categorias e Etiquetas

Dois endpoints devolvem a taxonomia completa de categorias e etiquetas do seu blog. São úteis para ferramentas externas que precisam de mapear categorias ou etiquetas do Nolorem para a sua própria taxonomia (por exemplo, um conector Drupal a fazer corresponder categorias do Nolorem a termos de vocabulário do Drupal). Ambos aceitam o parâmetro blog.

# Todas as categorias da sua organização (ou do blog delimitado)
curl "https://nolorem.io/api/v1/categories?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Todas as etiquetas da sua organização (ou do blog delimitado)
curl "https://nolorem.io/api/v1/tags?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Ambos devolvem a lista completa numa única resposta (não paginada):

{ "data": [{ "id": "uuid", "name": "Marketing" }, { "id": "uuid", "name": "Technology" }] }

Aplicam-se o mesmo token bearer, o mesmo requisito de plano Premium e o mesmo âmbito posts:read que nos endpoints de artigos.

Análise de Utilização por Chave

Nas Definições, cada linha de chave pode ser expandida para mostrar análises de utilização:

• Pedidos (últimas 24h / total): quantas chamadas à API esta chave fez.
• Fontes distintas: quantos endereços IP distintos e aplicações cliente utilizaram esta chave recentemente.
• Última utilização: a data e hora do pedido autenticado mais recente.

Estas análises ajudam-no a compreender como as suas chaves estão a ser utilizadas e a identificar padrões inesperados.

Sinalização de Partilha de Chaves

Se uma chave apresentar um grande número de endereços IP distintos num curto período, o Nolorem pode sinalizá-la como "possivelmente partilhada ou comprometida". A sinalização aparece como um aviso âmbar na linha da chave. A chave continua a funcionar, e não é tomada qualquer ação automática: trata-se de um sinal informativo.

Quando vir a sinalização, reveja os seus registos de utilização. Se partilhou a chave intencionalmente (por exemplo, com vários servidores num cluster), pondere se o padrão de acesso é o esperado. Se a chave puder ter sido divulgada ou partilhada com partes não pretendidas, revogue-a e crie uma nova para limitar o acesso.

Limites de Taxa

Cada chave de API está sujeita a estes limites:

• 60 pedidos por minuto
• 5 000 pedidos por dia

Quando excede um limite, a API devolve HTTP 429 com um cabeçalho Retry-After que indica quantos segundos deve esperar antes de tentar novamente:

HTTP/1.1 429 Too Many Requests
Retry-After: 43

{ "error": "Rate limit exceeded" }

Implemente recuo exponencial para scripts de sincronização fiáveis e de longa duração.

Códigos de Erro

Estado	Significado
400	Parâmetros de consulta inválidos
401	Chave de API em falta ou inválida
403	Plano Premium necessário, a chave não tem o âmbito posts:read, ou uma chave delimitada a um blog utilizada com um valor ?blog= que não corresponde
404	Artigo não encontrado
429	Limite de taxa excedido (verifique o cabeçalho Retry-After)

Especificação Legível por Máquina

A especificação completa da API no formato OpenAPI 3.1 está disponível em:

GET /api/v1/openapi.json

Este endpoint não é autenticado. Pode importá-lo para o Postman, o Insomnia ou qualquer ferramenta compatível com OpenAPI.

Revogar uma Chave

Para revogar uma chave, desloque-se até à secção Chaves de API nas Definições, encontre a chave pelo nome e clique em Revogar. A chave deixa de funcionar imediatamente. Os pedidos em curso que já tinham sido autenticados serão concluídos, mas nenhum novo pedido com a chave revogada será bem-sucedido.