GET, POST vagy QUERY? Mit jelent az új HTTP metódus az üzleti API-kban?

A jó API akkor is érthető, amikor már évek óta használják

Egy céges API ritkán marad egyetlen fejlesztő és egyetlen rendszer ügye. Először beköt egy weboldali űrlapot, később jön hozzá CRM, számlázó, riport, mobil app, partneri adatkapcsolat vagy belső adminfelület. Ami az első sprintben gyors megoldásnak tűnt, fél év múlva már üzleti működést visz.

Ilyenkor derül ki, mennyire beszédes maga az API. Egy kérésről ránézésre látszik-e, hogy csak adatot olvas? Biztonságosan újrapróbálható-e, ha megszakad a kapcsolat? Naplóban, monitoringban és hibajegyben visszakereshető-e, mi történt? A metódusválasztás apró technikai részletnek tűnik, mégis ezekre a kérdésekre ad első választ.

2026 júniusában megjelent az RFC 10008, amely szabványosítja a HTTP QUERY metódust. Ettől még holnaptól nem kell minden API-t átírni. A jelentősége inkább abban van, hogy kevesebb legyen a kényszerű kompromisszum: túl hosszú GET URL-ek és olvasási célra használt POST kérések között.

GET, POST vagy QUERY: a metódus üzleti ígéretet is hordoz

Egy HTTP metódus az endpoint első jelentésrétege. A kliens, a szerver, a cache, a proxy, a naplózás és az üzemeltetés is következtet belőle. Ha egy kérés GET, akkor olvasásra számítunk. Ha POST, akkor a szerver oldalon történhet változás. A QUERY ebbe a logikába hoz be egy hiányzó darabot: a bonyolultabb olvasási kérést, ahol a bemenet már kényelmesebb bodyban, de a művelet továbbra is lekérdezés.

Ez nagyon gyakorlati fejlesztői és üzemeltetési kérdés. Ha a metódus félrevezető, az üzemeltetés is nehezebben olvas jeleket. Egy hibásan újrapróbált POST duplikált rendelést, kétszer elküldött emailt vagy rossz státuszt okozhat. Egy POST mögé rejtett olvasás viszont kevésbé világos a naplókban, cache-ben és API dokumentációban.

Miért fáj később, ha minden összetett kérés POST?

Sok API azért használ POST-ot keresésre, mert a GET URL túl hosszú lenne, vagy a szűrési feltételek kényelmetlenül néznének ki query paraméterként. Ez érthető megoldás volt ott, ahol nem volt jobb szabványos út. A gond akkor kezdődik, amikor a rendszer többi része már nem tudja eldönteni, mi történik valójában.

Képzeljünk el egy admin riportot, amely ügyfelekre, dátumtartományra, státuszra, termékre és jogosultsági körre szűr. A kérés hosszú, a bemenet strukturált, a válasz fontos üzleti adat. Ha ez POST, a szerveroldali logból még nem derül ki, hogy olvasás történt-e vagy műveletindítás. Ha az integráció később lassul, cache-elni kellene, újrapróbálás kellene, vagy trace alapján kell hibát keresni, a homályos szemantika visszaüt.

Hogyan tervezzünk tiszta, hosszú távon karbantartható API-t?

A karbantartható API első szabálya, hogy minden végpontnak világos szerepe legyen. A név, a metódus, a bemenet, a válasz és a hibakód ugyanazt a történetet mondja. Ha az endpoint keres, akkor keres. Ha ment, akkor ment. Ha folyamatot indít, akkor ezt a kliens és az üzemeltetés is értse.

• Legyen különválasztva az olvasás, az állapotváltoztatás és a hosszú ideig futó művelet.
• A kliens tudja, melyik kérés próbálható újra biztonságosan kapcsolatvesztés után.
• A hibakódok legyenek következetesek: validációs hiba, jogosultsági hiba, hiányzó erőforrás és feldolgozási hiba ne mosódjon össze.
• A szűrés, rendezés, lapozás és jogosultsági határ legyen dokumentált, különösen riportoknál és adminfelületeknél.
• Minden üzletileg fontos kéréshez legyen trace azonosító, mérhető válaszidő és naplózható döntési pont.
• A verziózás ne utólagos tűzoltás legyen; már az első külső integráció előtt érdemes eldönteni, hogyan élnek tovább a régi kliensek.

A QUERY önmagában nem oldja meg ezeket. Jó ürügy viszont arra, hogy az API-tervben rákérdezzünk a szemantikára. Ahol a rendszer csak adatot olvas, ott ezt érdemes láthatóvá tenni. Ahol üzleti állapot változik, ott legyen egyértelmű, milyen mellékhatás, jogosultság, idempotencia és visszavonási lehetőség tartozik hozzá.

Mikor érdemes QUERY-ben gondolkodni?

A QUERY azokban a rendszerekben lehet igazán érdekes, ahol sok az összetett, strukturált olvasás. Ilyen lehet egy B2B portál ajánlatkeresője, belső admin riportja, jogosultságfüggő keresése, készlet- vagy rendeléslekérdezése, ERP kapcsolat, CRM szinkron előnézet vagy több feltételes elemzés.

Nem kell minden keresést QUERY-re cserélni. Egy termékoldal, listaoldal vagy egyszerű státuszlekérdezés továbbra is jól működik GET-tel. A döntési pont ott jelenik meg, ahol az URL már túl hosszú, a bemenet strukturáltabb, a szűrés érzékeny adatot is érinthet, és fontos, hogy a kérés továbbra is olvasásként viselkedjen.

Az API akkor jó, ha üzemeltetni is lehet

Egy API nem a Swagger dokumentációnál ér véget. Éles működésben számít a válaszidő, a hibaarány, a naplózás, az auditálhatóság, a jogosultsági modell, a rate limit, a visszajátszás elleni védelem és a kulcskezelés. Ezeket sokkal könnyebb jól megoldani, ha az endpointok szerepe tiszta.

A jól tervezett API-ban a fejlesztő gyorsabban ért hibát, az üzemeltetés hamarabb lát kockázatot, a külső integrátor kevesebbet találgat, az ügyfél pedig stabilabb üzleti folyamatot kap. Ez a valódi haszna annak, hogy GET, POST és QUERY között nem megszokásból döntünk.

A jó API tisztaságát az adja, hogy minden kérésről érthető: mit tehet, milyen hatása van, és hol látszik majd az üzemeltetésben.

Ha az API-ra üzleti folyamat épül, érdemes időben ránézni

Az 1data egyedi webalkalmazásoknál, integrációknál és belső adminfelületeknél nem elszigetelt endpointokat tervez. Azt nézzük, milyen üzleti folyamat fut az API mögött, milyen rendszerek kapcsolódnak hozzá, hol kell mérni, naplózni, jogosultságot kezelni, visszalépni vagy később bővíteni.

Ha készül egy új integráció, vagy már van egy API, amelyhez egyre több belső és külső rendszer csatlakozik, érdemes átnézni a metódusokat, a hibakezelést, a verziózást, a szűréseket, a trace-elést és az üzemeltetési jeleket. Sok későbbi fejlesztési költség ott dől el, amikor még csak pár végpont látszik a tervben.