Quem nunca ficou na dúvida?

Ao iniciar a criação de uma REST API surgem dúvidas do tipo:

• Qual a melhor maneira de fazer filtros?
• Como defino as ordenações?
• Paginação: Faço ou não faço?
• Como enviar os relacionamentos (joins) desejados?
• Ainda sobre os relacionamentos, como estruturar o JSON de resposta?

São apenas algumas dúvidas que surgem, mas fique tranquilo, você não é único que passou por isso.

Ainda bem que não sou o único que tem essa dúvida!

Quem decidiu escrever um padrão para resolver este problema foi o pessoal da Cerebris.

O nome deste projeto é JSON API e foi comandado por Dan Gebhardt, que é membro do core-team do EmberJS.

Dentro da comunidade do EmberJS o padrão JSON API é bem difundido, mas Dan e sua equipe resolveram compartilhar este trabalho com outras comunidades. Sorte a nossa!

Mas como eu não fiquei sabendo disso antes?

O JSON API começou em 2013 e sua principal versão foi lançada em 2015. Então isso já é algo estável e não é uma novidade.

Você provavelmente não sabia disso, porque o GraphQL surgiu na mesma época e acabou ofuscando o JSON API.

Sobre o GraphQL, eu sinceramente acho que seja um projeto muito legal e que resolve muitos problemas. Porém, o legado deixado pelas REST API é bem grande.

O foco deste artigo não é comparar REST API com GraphQL, uma vez cada uma tem suas vantagens e desvantagens. Mas é fato que cada tecnologia tem seu espaço e esta concorrência é vantajosa para nós programadores.

JSON API: Vamos direto ao ponto

O padrão JSON API define um conjunto de convenções de como uma REST API deve ser estruturada. A começar pelos filtros, que são muito comuns nas requisições GET que solicitam uma coleção de registros.

GET /people?filter[name]=john&filter[age_less]=18

As ordenações devem ser feitas da seguinte maneira:

GET /people?sort=name,age

Quando você precisar paginar os registros utilize page[limit]  e page[offset] :

GET /people?page[limit]=20&page[offset]=0

Uma das partes mais úteis do JSON API, é a convenção dos relacionamentos. Quando você precisar um relacionamento, você deve solicitar ao servidor da seguinte maneira:

GET /people?include=country

É claro que o JSON de retorno também é padronizado e segue esta estrutura:

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

GET /people?filter[name]=john&filter[age_less]=18&sort=name,age&page[limit]=20&page[offset]=0&include=country

{
  "data": [{
    "type": "people",
    "id": "1",
    "attributes": {
      "name": "John Silver",
      "age": "16"
    },
    "links": {
      "self": "http://example.com/people/1"
    },
    "relationships": {
      "country": {
        "links": {
          "self": "http://example.com/people/1/relationships/country",
          "related": "http://example.com/people/1/country"
        },
        "data": {
          "type": "countries",
          "id": "55"
        }
      }
    }
  }],
  "included": [{
    "type": "countries",
    "id": "55",
    "attributes": {
      "name": "Brazil",
      "continent": "South America"
    },
    "links": {
      "self": "http://example.com/countries/55"
    }
  }],
  "links": {
    "first": "http://example.com/people?filter[name]=john&filter[age_less]=18&sort=name,age&page[limit]=20&page[offset]=0&include=country",
    "last": "http://example.com/people?filter[name]=john&filter[age_less]=18&sort=name,age&page[limit]=20&page[offset]=0&include=country"
  }
}

Na minha opinião esse retorno padronizado é umas melhores funcionalidades do JSON API. A maneira como os relacionamentos ficam dispostos, os atributos bem organizados e os links para paginação são fantásticos.

Várias bibliotecas que economizam seu tempo

Você pode pensar: Quanto tempo demoraria para eu codificar isso tudo? Na verdade existem inúmeras bibliotecas para as mais diversas linguagens que podem te ajudar.

Posso dizer por mim, eu utilizo várias bibliotecas Open Source compatíveis com o padrão JSON API. Além de deixar minhas API's dentro de um padrão global, ainda me tornei muito produtivo, uma vez que não preciso me preocupar com todos os detalhes da REST API.

Segue link com uma listagem das bibliotecas mais populares que são compatíveis com JSON API:

• Bibliotecas JSON API

Não acabou, só falei o mais importante

Se você gostou, recomendo que leia a documentação completa. Existem outros tópicos que podem lhe interessar.

Dúvidas ou sugestões é só entrar em contato. Abraço.