API
REST API
Kaip naudoti DevData REST API?
REST API endpoint'as yra https://api.devdata.lt. Kiekvienoje užklausoje reikalinga Authorization antraštė su jūsų API raktu:
Authorization: Bearer sk_live_a1b2c3d4...
Atsakymai grąžinami JSON formatu. Užklausa be antraštės arba su atšauktu raktu grąžins 401 Unauthorized.
Patikrinti, ar raktas veikia
Naudokite /status. Endpoint'as patvirtina autentifikaciją ir grąžina plano informaciją.
curl https://api.devdata.lt/status \
-H "Authorization: Bearer sk_live_..."
{
"object": "ping",
"status": "ok",
"user": {
"id": 42,
"email": "[email protected]",
"plan_key": "basic"
},
"checks": {
"is_subscribed": false,
"current_plan_key": "basic",
"weekly_limit": 100,
"weekly_used": 3,
"weekly_remaining": 97,
"can_make_request": true
}
}
Kiek dar užklausų likę
Du būdai pamatyti kvotos būseną.
Antraštės kiekviename atsakyme. Užklausos grąžina savaitės kvotos antraštes:
X-RateLimit-Limit-Week: 2000
X-RateLimit-Remaining-Week: 1947
Limit-Week yra plano savaitės limitas, Remaining-Week parodo, kiek dar liko atlikti užklausų iki savaitės pabaigos. Kvota atsinaujina kiekvieną pirmadienį 00:00.
Šalia savaitės limitų veikia minutės užklausų apsauga nuo staigių šuolių. Ją viršijus gausite 429 su limit ir reset_at laukais. 429 taip pat gausite išnaudoję savaitės limitą.
/usage endpoint'as. JSON forma, patogi rodyti vartotojui savo aplikacijoje:
curl https://api.devdata.lt/usage \
-H "Authorization: Bearer sk_live_..."
{
"object": "usage",
"plan": "pro",
"weekly_limit": 2000,
"weekly_used": 680,
"weekly_remaining": 1320
}
Klaidos
Įvykus klaidai grįš toks atsakymas:
{
"error": {
"type": "not_found_error",
"code": "company_not_found",
"message": "Company not found",
"doc_url": "https://devdata.lt/docs/errors#company_not_found",
"request_id": "req_01HXYZ..."
}
}
type yra klaidos kategorija (invalid_request_error, authentication_error, permission_error, not_found_error, rate_limit_error, api_error), o code tikslesnė priežastis. Programuokite pagal code. request_id pravers, jei kreipsitės į pagalbą.
| HTTP | Code | Reikšmė |
|---|---|---|
| 400 | invalid_param |
Neteisingas parametras ar filtras; validacijos atveju pridedami param ir errors laukai |
| 400 | method_not_allowed |
Endpoint'as nepalaiko šio HTTP metodo |
| 401 | invalid_token |
Raktas neteisingas arba atšauktas |
| 401 | unauthenticated |
Užklausa be Authorization antraštės |
| 403 | api_key_suspended |
Raktas laikinai sustabdytas (pvz., įtarus nutekėjimą); žr. el. paštą |
| 404 | not_found |
Kelias neegzistuoja |
| 404 | *_not_found |
Resursas nerastas, pvz., company_not_found |
| 429 | rate_limit_exceeded |
Viršytas savaitės limitas; atsakyme yra limit ir reset_at |
| 500 | internal_error |
Mūsų pusės klaida |
Retry
5xx ir 429 klaidos dažniausiai būna laikinos. Jos gali rodyti mūsų sistemos perkrovą, deploy momentą arba trumpalaikę problemą, todėl tokias užklausas verta pakartoti po kelių sekundžių. Dažnai pavyks iš antro karto. 429 atveju atsakymo reset_at laukas pasako, kada limitas atsinaujins.
Jei klaidos kartojasi, kreipkitės į [email protected] su request_id.
4xx klaidų (išskyrus 429) kartoti nereikia. Užklausa neteisinga, todėl pakartojimas tik eikvos užklausas.
Pilna specifikacija
Visus endpoint'us, schemas ir filtrus rasite api.devdata.lt/docs. Įkėlę savo raktą galite išbandyti API tiesiai naršyklėje.