Ações e estados

O princípio

Status é dado; mudar de status é comportamento. Quando uma transição de estado tem efeito no mundo, ela ganha um endpoint de ação próprio, em vez de ser um campo que o cliente escreve.

Quando a mudança é uma ação própria

Use um endpoint de ação (um verbo no recurso) quando a transição:

• Tem efeito colateral (ex.: publicar chama Instagram, LinkedIn).
• É irreversível (saiu para o mundo).
• É assíncrona (entra em fila, pode falhar ou ser parcial).
• Exige permissão ou validação diferentes da criação.

Quando basta um campo

Se o estado é só um rótulo, sem efeito, ele pode ser um campo em create/update — por exemplo o progresso de uma tarefa.

Exemplo: Blog

Por isso a API cria um rascunho (POST /posts) e publica por uma ação própria (POST /posts/{post}/publish). O estado do post é documentado no recurso, mas a transição com efeito público acontece por um endpoint explícito.