Kihagyás

Áttekintés

Bevezetés

A CapITris API a hívások lebonyolításához szükséges adatok feltöltésére és a hívás során keletkezett adatok letöltésére szolgál.

A CapITris API egy (REST-like) HTTP API, amely JSON formátumban tud adatokat fogadni és visszaadni.

Titkosítás: minimális követelmény

TLS1.2

Autentikáció

A CapITris API állapotmentes; minden kérésnek autentikálnia kell magát a szerver felé. Ez az api_key nevű, URL paraméterrel történik.

Amennyiben valamely operáció másfajta autentikációt igényel, vagy nem igényel autentikációt (pl. publikus operáció, mint pl. a /sound/getfilebyhash) ott ezt külön jelezzük.

A CapITris API plain HTTP-n keresztül nem elérhető (csak HTTPS-en keresztül).

Hibakezelés

A kliensnek fel kell készülnie, hogy bizonyos hibák esetén a válasz üres, és a státusz kód jelzi a hibát. A legtöbb hiba esetén azonban a státusz kód 200 (ok), és a hiba a JSON tartalomban jelenik meg. Hiba esetén az alábbi JSON-t kapjuk vissza:

    {
        "status": "error",
        "error": "An error occured."
    }

Ez a JSON válasz bármely API végpont esetén visszajöhet, ezt nem írjuk le külön minden végpont leírásánál.

A kérések URL-je

A CapITris API végpontok gyűjteménye. Egy végpont egy entitás és egy művelet kombinációja. A kérések URL-je a következőképpen alakul:

https://api.capitris.hu/v3/api/[ügyfélkód]/[entitás]/[művelet]?api_key=...

Az egyes végpontok tárgyalásánál az URL-nek csak a következő részét írjuk le:

/[entitás]/[művelet]

Karakterkódolás

A kéréseknek utf-8 kódolással kell érkeznie

Content-type: application/json; charset=utf-8

Gyakori műveletek

Az általános, sokféle entitásnál használatos műveleteket igyekszünk egységesen nevezni. Gyakran előforduló műveletek a következők:

  • list : Entitások listáját kéri le jellemzően szűrési lehetőségekkel.
  • get : Egy bizonyos entitást kér le, jellemzően egy ID alapján.
  • new : Egy új entitás felvitele.
  • update : Egy entitás módosítása. Itt az azonosítón kívül a kérés minden mezője opcionális, és csak az módosul, ami a kérésben ki van töltve.
  • delete : Egy entitás törlése.

A kérések adatai

A kéréseket alapvetően HTTP POST metódussal kell a szervernek elküldeni. (Amennyiben csak URL-paramétereket használunk, támogatva van a HTTP GET metódus is, de ezt csak teszteléshez javasoljuk.) A kérések adatait JSON formátumban, vagy az URL-ben, URL paraméterekkel is küldhetjük. Ezek kombinálhatóak is.

A kéréseknek utf-8 kódolással kell érkeznie: "Content-type: application/json; charset=utf-8"!

A kéréseket ebben a dokumentumban minden esetben JSON-ban definiáljuk. A kérés JSON objektum közvetlen mezői aztán áttehetőek az URL-be, de értelemszerűen egy mélyebb JSON hierarchia már csak JSON-ban postolható. Például ha a kérés definíciója a következő:

    {
        "sample_param1": true,
        "sample_param2": 12
    }

akkor pl. küldhetőek a kérés paraméterei URL-ben a következőképpen:

POST /v3/api/sample_client/sample_entity/sample_action?sample_param1=true&sample_param2=12

A kéréseknél egyes mezők kötelezőek, mások opcionálisok, ezt mindig külön jelezzük.

A leírásban a következő adattípusokat használjuk:

  • integer: JSON number, de csak egész értéket vehet fel
  • szám: JSON number
  • szöveg: JSON string. Amennyiben egy hívás során maximálva van egy szöveg mérete, a mérethatárt zárójelben feltüntetjük. Pl.: szöveg(50): maximum 50 karakter hosszú szöveg.
  • boolean: JSON boolean
  • dátum: JSON string, ÉÉÉÉ.HH.NN formátumban.
  • időpont: JSON string, ÉÉÉÉ.HH.NN ÓÓ:PP:mm vagy ÉÉÉÉ.HH.NN ÓÓ:PP:mm:MMM formátumban (tehát a milliszekundumok opcionálisok).
  • időtartam: JSON string, ÓÓ:PP:mm formátumban.
  • tömb: JSON array
  • objektum: JSON object

Egy kérés payloadjának mérethatára 10 Megabyte. Ennek a korlátnak jelenleg elsősorban a listitem/bulknew operáció esetében lehet relevanciája.

A válaszok adatai

A válaszokban a nem megadott mezők nem null-t, hanem számok esetén 0-t, sztringek esetén üres sztringet tartalmaznak.