REST API
REST API
A superfície para scripts e integrações. JSON puro, paginado, sem OData no caminho — para quando você quer os dados dentro do seu próprio código.
- Base
https://service.agrosti.com.br/v1/- Autenticação
Authorization: Bearer oag_...- Coleções
- 50
- Escrita
- Não — a superfície é somente leitura
Uma requisição
curl -H "Authorization: Bearer oag_SEU_TOKEN" \
"https://service.agrosti.com.br/v1/openagros/harvest?pageSize=200&page=1"Toda coleção responde com o mesmo envelope:
{
"items": [ ... ],
"page": 1,
"pageSize": 100,
"total": 1041
}| Campo | É |
|---|---|
items | As linhas da página, no schema da coleção |
total | O total da coleção, não da página. Pagine até alcançá-lo |
page / pageSize | Repetem os valores que você enviou |
Paginação
page começa em 1 e pageSize vai até
200. Sem os dois parâmetros, a coleção vem inteira — o que
é conveniente em cadastros pequenos e uma péssima ideia num fato de centenas
de milhares de linhas.
O que o REST não faz
A querystring aceita apenas page e
pageSize. Não há $filter nem
$orderby: o recorte é do lado do cliente, depois de baixar a
coleção.
A consequência prática é o critério de escolha entre as duas superfícies. Se você vai recortar por safra, fazenda ou período — e num fato agrícola quase sempre vai —, OData dobra esse filtro no servidor e transfere só o que interessa. O REST transferiria a coleção toda.
Aquela coleção exige filtro de data pelo volume, e o REST não
tem como expressá-lo. Toda chamada responde
400 FilterRequired. Use a
versão OData.
Limite de requisições
60 requisições por minuto por token, no máximo — o valor de cada
token é escolhido na criação e nunca passa desse teto. Ao estourar, a resposta
é 429: espere a virada do minuto e repita. Como o REST não
filtra no servidor, é a superfície que mais gasta requisição em coleção
grande; se você está batendo no limite com frequência, o problema
provavelmente se resolve em OData.
Erros
Os mais comuns aqui. A lista completa, com o formato do corpo do erro, está em Erros.
| Código | Significa |
|---|---|
401 | Token ausente, inválido, revogado ou expirado |
403 | O token não tem o escopo daquela coleção |
400 FilterRequired | A coleção exige um filtro que o REST não expressa |
429 | Limite de requisições por minuto estourado |
Coleções
As 50 coleções, campo a campo, estão no menu à esquerda. Os fatos — o que você soma — são o ponto de partida: