API: első lépések

A REST API-val egy alkalmazás vagy szkript SRVO-műveleteket hívhat meg. Az SRVO Cloud címe: https://api.srvo.app/api/v1. Saját üzemeltetésű SRVO esetén a szervered címe után írd az /api/v1 útvonalat.

API-kulcs létrehozása

1. Az SRVO-ban nyisd meg a Beállítások → API, MCP és webhookok oldalt.
2. Az API-kulcsok résznél válaszd a Személyes vagy Munkaterületi lehetőséget. Munkaterületi kulcsot csak tulajdonos vagy adminisztrátor kezelhet.
3. Válaszd a Kulcs létrehozása lehetőséget, adj meg egy Neve értéket, majd válassz Hatókört:
   • A Csak olvasás adatolvasást enged.
   • Az Olvasás és írás támogatott módosításokat is enged.
4. Válaszd ki, mely műveleteket használhatja a kulcs. A saját szerepköröd és jogosultságaid továbbra is érvényesek.
5. Állítsd be a lejáratot, majd válaszd a Kulcs létrehozása lehetőséget.
6. Másold ki és tárold biztonságosan a kulcsot. Az SRVO csak egyszer mutatja meg. Válaszd az Elmentettem lehetőséget.

Csak a szükséges hatókört és műveleteket engedélyezd. Ha már nincs szükséged a kulcsra, vond vissza a Beállításokban.

Első kérés

Tedd a kulcsot környezeti változóba. Ne írd be közvetlenül a parancsba, és ne mentsd a forráskódba.

export SRVO_API_KEY='your-key'
curl --fail-with-body \
  -H "Authorization: Bearer $SRVO_API_KEY" \
  https://api.srvo.app/api/v1/me

A GET /api/v1/me a munkaterületed, tagod, szerepköröd és elérhető moduljaid adatait adja vissza. Az API JSON-adatot ad vissza. Minden kéréshez küldd el a bearer tokent.

Lista olvasása

Az oldalakra bontott listák kurzort használnak, ha ezt a művelet sémája támogatja. Az alapértelmezett oldalméret 50, a maximum 200. Kövesd a nextCursor értéket, amíg null nem lesz.

Például a GET /tables/{tableId}/records útvonal a cursor és limit értéket lekérdezési paraméterként várja. Egyes olvasások összetett szűrőt vagy más strukturált adatot igényelnek, ezért POST kérések. Ilyen a POST /search/query, a taxonómiaelőzmények és a Sergio-listák. Ezeknél a kurzort és szűrőket a JSON-törzsbe tedd, ha a referencia ott jelzi. Minden művelet részleteit nézd meg az API-referenciában.

Írások biztonságos újrapróbálása

Egyes írások Idempotency-Key fejlécet fogadnak el, másoknál az idempotencyKey mező használható. Mindig az adott műveletnél feltüntetett mezőt használd. Készíts egyedi kulcsot a kívánt íráshoz, és időtúllépés utáni újrapróbáláskor használd ugyanazt. Másik íráshoz ne használd fel. Az API-referencia jelzi, mely műveletek fogadnak el kulcsot.

Hibák és korlátok kezelése

A hiba JSON-adatként érkezik, az error.code mezővel. Ilyen kód például: VALIDATION, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, STALE_PREVIEW és RATE_LIMITED. A HTTP-státuszok között a 400 hibás adatot, a 401 hiányzó bejelentkezést, a 403 tiltott vagy kikapcsolt modult, a 404 hiányzó vagy rejtett elemet, a 409 ütközést, a 429 pedig sebességkorlátot jelent.

Az alapértelmezett általános korlát percenként 600 kérés minden ellenőrzött munkamenetre vagy API-kulcsra. A névtelen kérések IP-címenként kapnak percenként 600 kérést. Ha a válasz tartalmaz Retry-After fejlécet, az ott megadott másodperc után próbálkozz újra. A korlát útvonalanként és szerverbeállítástól függően változhat.

Romboló művelet előnézete

Egyes romboló műveletekhez két kérés kell. Először hívd meg a műveletet megerősítés nélkül. Ekkor előnézetet kapsz. Nézd át az összefoglalót és a figyelmeztetéseket. Ezután hívd meg újra a műveletet az előnézetben kapott megerősítési értékkel. A mező vagy fejléc műveletenként eltérhet. Elavult előnézet esetén kérj újat. A referencia leírja az egyes műveletek megerősítési módját.

Generált fejlesztői referencia.