Sugestão para facilitar a nevegação na API

[msfernandes]

Boa noite :)

Estou fazendo um wrapper em python para a nova API de dados abertos. E vi que a forma atual de navegação não está tão boa de utilizar:

  "links": [
    {
      "rel": "self",
      "href": "https://dadosabertos.camara.leg.br/api/v2/deputados?ordem=ASC&ordenarPor=nome"
    },
    {
      "rel": "next",
      "href": "https://dadosabertos.camara.leg.br/api/v2/deputados/?pagina=2&itens=15"
    },
    {
      "rel": "first",
      "href": "https://dadosabertos.camara.leg.br/api/v2/deputados/?pagina=1&itens=15"
    },
    {
      "rel": "last",
      "href": "https://dadosabertos.camara.leg.br/api/v2/deputados/?pagina=33&itens=15"
    }
  ]

No caso acima, por exemplo, eu teria que iterar essa lista e colocar um if pra saber qual rel é o "next". Fica meio ruim :( Além de que quando não tem página, esses campos apenas deixam de existir, o que também dificulta pra fazer algo genérico.

Minha sugestão seria algo do tipo:

"links": {
    "self": "https://dadosabertos.camara.leg.br/api/v2/deputados?ordem=ASC&ordenarPor=nome",
    "next": "https://dadosabertos.camara.leg.br/api/v2/deputados/?pagina=2&itens=15",
    "first": "https://dadosabertos.camara.leg.br/api/v2/deputados/?pagina=1&itens=15",
    "last": "https://dadosabertos.camara.leg.br/api/v2/deputados/?pagina=33&itens=15"
}

Dessa forma, o acesso é direto: links["next"], por exemplo. Além disso, esses campos deveriam estar presentes sempre, atribuindo o valor null quando eles não existirem. Por exemplo:

"links": {
    "self": "https://dadosabertos.camara.leg.br/api/v2/deputados?ordem=ASC&ordenarPor=nome",
    "next": null,
    "first": "https://dadosabertos.camara.leg.br/api/v2/deputados?ordem=ASC&ordenarPor=nome",
    "last": "https://dadosabertos.camara.leg.br/api/v2/deputados?ordem=ASC&ordenarPor=nome",
}

Para quando só tiver uma página.

Bom, fica ai minha sugestão :)

Abraços!

[msfernandes]

Mais uma sugestão: ao invés desses links (self, next, first...) serem a URL toda, poderia ser só o path

[EquipeDadosAbertosCD]

Salve, moçada!

Essa estrutura dos links que adotamos na nova API é a mais frequentemente recomendada. Também foi (e continua) prevista na especificação do sistema a possibilidade de colocar as relações IANA diretamente como propriedades, mas optou-se pela estrutura mais verbosa e padronizada de "rel" e "href" porque, pelo menos em teoria, ela torna mais fácil o processamento de diversas relações IANA, especialmente quando tivermos outras além das relações de paginação.

Mas a discussão é boa. Vamos manter o tópico em aberto para que os argumentos contra e a favor apareçam, e dependendo do rumo podemos mudar a representação dos links em algum momento...

Abraços!

Fabricio Rocha Equipe Dados Abertos - Câmara

[nitaibezerra]

Opa,

Recentemente montamos no MinC uma API para a Lei Rouanet disponível em: api.salic.cultura.gov.br. Nela usamos alguns padrões interessantes (Swagger, hateoas e HAL). O HAL - Hypertext Application Language é um formato (applicatin/hal+json) simples para hiperlinkar os recursos da API. Ele recomenda o uso de da sintaxe como no exemplo abaixo:

    "_links": {
        "self": { "href": "/orders" },
        "curies": [{ "name": "ea", "href": "http://example.com/docs/rels/{rel}", "templated": true }],
        "next": { "href": "/orders?page=2" },
        "ea:find": {
            "href": "/orders{?id}",
            "templated": true
        },
        "ea:admin": [{
            "href": "/admins/2",
            "title": "Fred"
        }, {
            "href": "/admins/5",
            "title": "Kate"
        }]
    },
    "currentlyProcessing": 14,
    "shippedToday": 20,
    "_embedded": {
        "ea:order": [{
            "_links": {
                "self": { "href": "/orders/123" },
                "ea:basket": { "href": "/baskets/98712" },
                "ea:customer": { "href": "/customers/7809" }
            },
            "total": 30.00,
            "currency": "USD",
            "status": "shipped"
        }, {
            "_links": {
                "self": { "href": "/orders/124" },
                "ea:basket": { "href": "/baskets/97213" },
                "ea:customer": { "href": "/customers/12369" }
            },
            "total": 20.00,
            "currency": "USD",
            "status": "processing"
        }]
    }
}

O uso do HAL reduz a complexidade para consumo da API, inclusive existem diversas bibliotecas que suportam o formato HAL

Nitai TI do MinC