O que e JSON:API?

JSON:API e uma especificacao para criar APIs baseadas em JSON com uma estrutura de resposta consistente. Ela define convencoes para recursos, relacionamentos, links, erros, selecao de campos, ordenacao, filtros e paginacao.

JSON continua sendo o formato dos dados. JSON:API e o conjunto de regras que organiza esses dados em uma API.

Como uma resposta JSON:API se parece

Uma resposta simples geralmente envolve o recurso em data:

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API basics"
    }
  }
}

type e id identificam o recurso. attributes guarda campos comuns. relationships pode descrever relacoes com outros recursos sem obrigar cada endpoint a inventar um formato diferente.

Por que equipes usam JSON:API

JSON:API ajuda quando varios clientes precisam consumir payloads previsiveis:

• Frontends conseguem interpretar respostas com convencoes compartilhadas.
• Erros de API seguem uma estrutura mais estavel.
• Paginacao, links e relacionamentos ficam consistentes entre endpoints.
• A documentacao pode focar nos campos do recurso, nao no formato externo de cada resposta.

Ela reduz convencoes proprias em produtos maiores.

Quando JSON:API pode ser demais

JSON:API tambem e mais estruturada do que muitas APIs pequenas precisam. Para um servico interno simples, uma resposta JSON direta pode ser mais facil de ler e manter.

Considere JSON:API quando a API tem muitos tipos de recurso, relacionamentos, clientes e contratos duradouros. Evite quando o envelope extra atrapalhar mais do que ajudar.

Dica pratica

Ao depurar uma resposta JSON:API, comece por data, attributes, relationships, included e errors. Cole um exemplo no Formatador JSON para expandir a estrutura antes de comparar com documentacao ou schemas.