Paginação

Em todas as operações de consultas que retornem listas, a aplicação fornece um mecanismo de paginação. Existem dois parâmetros: limit e offset. Ambos os parâmetros definem o tamanho do bloco dos resultados. Isso evita consumo excessivo de recursos do servidor e do client, além de otimizar a visualização da informação pelo usuário final.

Parâmetros de chamada

Parâmetro	Descrição	Valor padrão
`_limit`	Determina a quantidade de registros a serem retornados por página	50
`_offset`	Posição do registro de referência, a partir dele serão retornados os próximos N registros	0

Exemplo

GET /v1.0/marketplace/orders?_limit=10&_offset=0

Parâmetros da resposta

Parâmetro	Descrição	Valor padrão
`limit`	Retorna a quantidade específica de registros se houver	50
`count`	Quantidade de registros que foi retornada nessa página	0
`max_limit`	Refere-se ao valor máximo que pode ser utilizado no campo limit	0

Resposta

{
  "page": {
    "limit": 20,
    "offset": 150,
    "count": 1,
    "max_limit": 10
  }
}

Na consulta acima, a partir do registro #151, serão retornados os próximos 20 registros.

Para a demonstração vamos definir que o valor padrão é 50 e o valor máximo 200.

Exemplos

Chamada	Resultado
`/v1.0/marketplace/orders?_offset=150&_limit=20`	Serão retornados os próximos 20 registros, a partir do registro #151
`/v1.0/marketplace/orders?_offset=0`	Serão retornados os próximos 50 registros, a partir do primeiro registro
`/v1.0/marketplace/orders?_offset=0&_limit=1`	Será retornado o primero registro
`/v1.0/marketplace/orders?_offset=0&_limit=51`	Serão retornados os próximos 51 registros, a partir do primeiro registro
`/v1.0/marketplace/orders?_offset=0&_limit=200`	Serão retornados os próximos 200 registros, a partir do primeiro registro

Ordenação

A aplicação fornece a possibilidade de ordenar os valores das listagens, nos sentidos ascendente e descendente:

Identificador	Ordem	Exemplo
`?_sort=campo:asc`	Ascendente	`GET /v1.0/marketplace/orders?_sort=shipping.date:asc`
`?_sort=campo:desc`	Descendente	`GET /v1.0/marketplace/orders?_sort=shipping.date:desc`

Nota: Se não for especificado uma ordem após o nome do campo, é aplicada uma ordenação asc.

Ordenações com combinação de campos

Mais do que um critério de ordenação pode ser especificado na mesma URL

?_sort=campo1:asc,campo2:desc,campo3:asc

Quando os critérios são combinados, a regra de ordenação é aplicada uma sobre a outra, da esquerda para a direita.

Filtragem

Pesquisas

A aplicação tem mecanismos para que a coleção possa ser consultada através de filtros de busca. Esses critérios são sempre expressos na URL através de parâmetros de consulta.

Neste caso, a aplicação utiliza os nomes dos campos com todos os caracteres em minúsculo.

Identificador	Critério	Exemplo
`?campo=valor`	Valor exato	`GET /v1.0/marketplace/orders?id=175&code=ABC`
`?campo__like=valor`	Valor parcial `like`	`GET /v1.0/marketplace/orders?buyer.name__like=Daniel`
`?campo__in=valor_1,valor_2,valor_X`	Lista de valores `in`	`GET /v1.0/marketplace/orders?id__in=175,215,830`
`?campo__gt=valor`	Maior que `>`	`GET /v1.0/marketplace/orders?amount__gt=100`
`?campo__gte=valor`	Maior ou igual a `>=`	`GET /v1.0/marketplace/orders?amount__gte=100`
`?campo__lt=valor`	Menor que `<`	`GET /v1.0/marketplace/orders?amount__lt=100`
`?campo__lte=valor`	Menor ou igual a `=<`	`GET /v1.0/marketplace/orders?amount__lte=100`

Para fazer uso da função between, a aplicação utiliza Maior que ou Maior igual a e Menor que ou Menor ou igual a.

Os critérios se somam como um AND.

Quando a pesquisa envolver campos que estão modelados como objetos no body, a aplicação faz a referência através do caminho completo até o atributo - utilizando o separador ponto.

Por exemplo, para o seguinte body JSON:

{
  "buyer": {
    "_id": 1000,
    "name": "..."
  },
  "order": {
    "_id": 595
  }
}

A pesquisa seria assim:

GET /v1.0/orders?buyer._id=1000 & order._id=595

Limitações com parâmetros de consulta

A RFC do HTTP 1.1 não limita a quantidade de caracteres na URI, como pode ser verificado nos links:

https://tools.ietf.org/html/rfc2616#section-3.2.1

https://tools.ietf.org/html/rfc2068#section-3.2.2

No desenho de APIs sugerimos cautela ao utilizar URIs muito longas. Em geral, URIs muito longas são indicativos de que sua API pode não estar aderente aos padrões de mercado. A aplicação sugere modelar de alguma outra forma de maneira que se adeque ao padrão REST.

Em alguns casos pode-se encontrar restrições no servidor Web por motivo de segurança ou configuração fina de performance, em geral o parse pode causar lentidão no servidor.

Resposta:

{
  "meta": {
    "page": {
      "limit": 10,
      "offset": 0,
      "count": 1,
      "max_limit": 10
    },
    "links": {
      "previous": "/v1.0/marketplace/orders?_limit=10&_offset=0",
      "self": "/v1.0/marketplace/orders?_limit=10&_offset=10",
      "next": "/v1.0/marketplace/orders?_limit=10&_offset=20"
    }
  },
  "results": [
    {
      "sku": "ABC1232fd",
      "quantity": 2,
      "unit": "unit"
    }
  ]
}

O campo results retorna os dados esperados. O campo meta retorna as informações sobre as quantidades de registros encontrados, onde apenas o campo total é opcional. Os filtros aplicados na consulta, retornam o campo utilizado como filtro, o operador utilizado sendo representado pelos nomes: eq, like, in, gt, gte, lt, lte e o valor aplicado.

As ordenações identificam o campo e a ordenação (asc e desc) que foi aplicada, e as URLs de paginação, para obter os próximos registros ou os anteriores, se existirem, como a própria URL que foi consultada.

Webhooks Identificador de requisições (X-Request-ID)