APIs

Uma API é o que você publica: um nome, um endereço, uma política de autenticação e um conjunto de rotas e backends. Tudo o mais no produto pertence a uma API.

Campos

Campo	Regra
name	1 a 120 caracteres. Renomear não muda o identificador nem o endereço
slug	derivado do nome na criação; único dentro da organização; formato ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$
description	até 1000 caracteres; "" limpa, campo ausente mantém
default_hostname	<slug>-<6 caracteres base32>.<sufixo do produto>; fixado na criação; único no produto inteiro
lifecycle	ACTIVE, DISABLED ou ARCHIVED
publish_state	estado de publicação (ver Visão geral da API)
auth_mode	PUBLIC, API_KEY (padrão na criação) ou JWT_OIDC
draft_version	contador que muda a cada alteração de rota, backend ou política

Ciclo de vida

lifecycle	Significado
ACTIVE	operação normal
DISABLED	fora do ar: a desativação remove a API do runtime e confirma a ausência em todas as máquinas. Reativar reaplica a revisão publicada
ARCHIVED	valor reservado no contrato (aparece também como filtro de listagem). Não há operação hoje que leve uma API a ARCHIVED — desativar leva a DISABLED

Desativar não apaga nada: a revisão continua lá, e reativar é a mesma revisão voltando ao ar.

Excluir

Uma API ativa ou publicada não pode ser excluída: a resposta é 409 api_published. Desative antes.

A exclusão é lógica (deleted_at), e depois dela o nome e o identificador ficam livres na organização.

Alterações não publicadas

O produto compara o digest da configuração atual com o da revisão ativa. Se forem diferentes, has_unpublished_changes é true.

Mexer numa rota, num backend ou numa política não altera o comportamento da API em produção: só a publicação altera. Três exceções conscientes, que aplicam direto:

• consumidores, chaves e autorizações;
• endereços ativos e certificados;
• estado da organização (suspensa ou não).

Concorrência: duas pessoas editando

Cada leitura devolve um ETag com o draft_version. Ao alterar, envie If-Match com o valor lido; se outra pessoa alterou no meio, a resposta é 412 precondition_failed e você recarrega. Sem If-Match, a alteração é aplicada (última escrita vence) — use o cabeçalho em automação.

Limites

Limite	Valor
Nome	120 caracteres
Descrição	1000 caracteres
Identificador (slug)	40 caracteres
Tamanho do corpo administrativo	1 MiB (acima: 413 payload_too_large)
Rotas por API	não há limite declarado no contrato
Operações simultâneas por API	1

Criar uma API

curl -sS -X POST "$BASE/v1/apis" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: criar-api-pedidos-01' \
  -d '{"name":"Pedidos","description":"API de pedidos do ERP"}'

Resposta 201 (resumida):

{
  "id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
  "name": "Pedidos",
  "slug": "pedidos",
  "default_hostname": "pedidos-7hq2ab.gw.nnumbers.com.br",
  "lifecycle": "ACTIVE",
  "publish_state": "DRAFT",
  "auth_mode": "API_KEY",
  "draft_version": 1
}

O Location traz o endereço do recurso e o ETag o draft_version ("1").

Use Idempotency-Key nas operações de escrita: repetir a chamada com a mesma chave devolve a mesma resposta, sem criar outro recurso. Chave repetida com corpo diferente é 422 idempotency_key_reused.

Próximos passos

• Rotas e Backends: o que a API encaminha.
• Segurança e autenticação: PUBLIC, API_KEY e JWT_OIDC.
• Publicação: como o rascunho vira tráfego.