Specifikace RESTful API

Cílem tohoto dokumentu je specifikovat, jak je na straně serveru řešené API pro práci s formátem Short Payment Descriptor (SPAYD).

Primárním cílem RESTful API je postkytnout prostředky pro snadnou integraci formátu např. do e-shopu, na webové stránky dobročinné organizace nebo do online systémů pro správu faktur.

Sekundárním cílem je pak poskytnout referenční implementaci formátu a prostředky pro validaci in-house implementací formátu SPAYD.

Poslední, čemu může být RESTful API k užitku, je verfikace čísla IBAN za účelem např. zamezení podvodných QR kódů.

Umístění API

API je dostupné na základní adrese: http://api.paylibo.com/paylibo/.

Jsou k dispozici tyto zdroje:

• Validace řetězce SPAYD
• Verifikace IBAN protistrany
• Generování řetězce SPAYD – Parametry příkazu v ČR
• Generování souboru SPAYD – Parametry příkazu v ČR
• Generování QR kódu SPAYD – Parametry příkazu v ČR
• Generování řetězce SPAYD – základní parametry
• Generování souboru SPAYD – základní parametry
• Generování QR kódu SPAYD – základní parametry

Příklad – generování QR kódu pro platbu Českému červenému kříži:
http://api.paylibo.com/paylibo/generator/czech/image?accountNumber=222885&bankCode=5500&amount=250.00&currency=CZK&vs=333&message=FOND%20HUMANITY%20CCK

Formát specifikace API

Specifikace je strukturována dle jednotlivých zdrojů – ke zdroji je vždy uveden:

• Název funkčnosti (př.: “Validace řetězce SPAYD”, …).
• Adresa REST zdroje ve formátu ${API_PATH}/${VERSION}/${RESOURCE} – kde:
  • ${API_PATH} označuje tzv. “base URL”, čili to, kde je API dostupné – v dokumentaci se nesubstituuje
  • ${VERSION} označuje verzi API, v dokumentaci se substituuje za aktuální verzi API
  • ${RESOURCE} označuje název konkrétního zdroje, v dokumentaci se substituuje za název zdroje
• Parametry dotazu jsou zachyceny v tabulce (“název”, “typ”, “popis”), povinné parametry jsou zobrazeny tučně, nepovinné běžnou tloušťkou písma.
• HTTP metoda, která daný scénář realizuje (jedna z hodnot GET, POST, PUT či DELETE).
• Popis odpovědi, vč. popisu stavových kódů HTTP protokolu, a to jak v pozitivním (vše proběhlo v pořádku), tak v negativním (došlo k chybě) případě.

Obecné zásady API

Obecné zásady, kterými se API řídí, jsou následující:

• API je verzované, aby bylo možno zajistit kompatibilitu s různými verzemi klientů.
• API je postavené na filosofii REST, implementovanou nad protokolem HTTP (čili jedná se o tzv. RESTful API).
• Server důsledně dbá na vracení stavových kódů HTTP protokolu, aby bylo možno v případě negativní odpovědi serveru (při chybě) HTTP tento kód okamžitě interpretovat, a např. přerušit připojení, a šetřila se tak přenesená data.
• Veškerá komunikace bude probíhat po zabezpečeném kanále (HTTPS).

Mechanismus předávání chybových odpovědí

Komunikační protokol je navržen tak, aby bylo možno použít HTTP stavový kód jako indikátor úspěchu či neúspěchu dotazu na server. Úspěch je tedy indikován kódy 20x, neúspěch z důvodu klientské chyby kódy 40x a neúspěch z důvodu serverové chyby kódy 50x.
V případě neúspěchu libovolného typu je vrácena odpověď s tělem s MIME type application/json v následujícím formátu:

{
  “description”: “Popis chyby, ktery se ma zobrazit uzivateli”
  “errors”: [
    {
      “code”: “err001”,
      “description”: “Popis 1. parcialni chyby, napr. vadne pole formulare”
    },
    {
      “code”: “err002”,
      “description”: “Popis 2. parcialni chyby, napr. vadne pole formulare”
    }
  ]
}

Chybové odpovědi mohou být specifické pro daný zdroj (interpretace stavového kódu může být různá pro různé zdroje), ale některé z nich jsou obecné a společné všem zdrojům. Tyto chyby jsou indikovány následujícími HTTP kódy:

• 418 – Zastaralá verze klienta. Je nutné aktualizovat klientskou aplikaci.
• 503 – Služba není dostupná. Vrácen v případě provádění údržby serveru. Klientská aplikace upozorní uživatele, že služba bude dostupná později.

Popis datových typů

Rozhraní používá primárně primitivní datové typy podporované formátem JSON (string, number, object, array, true, false, null).

Popis zdrojů API

Validace řetězce SPAYD

URL: ${SERVER}/validator/string
Metoda: GET
Parametry:

Odpověď v negativním případě:

Odpověď v pozitivním případě:

Verifikace IBAN protistrany

URL: ${SERVER}/validator/iban
Metoda: GET
Parametry:

Odpověď v negativním případě:

Odpověď v pozitivním případě:

{
    "result": "unknown",
    "iban": "CZ1212341234561234567890"
}

{
    "result": "banned",
    "iban": "CZ1212341234561234567890",
    "reason": "Podvodný IBAN"
}

{
    "result": "verified",
    "iban": "CZ1212341234561234567890",
    "name": "Ticket Pro",
    "description": "TICKETPRO provozuje v ČR
                    největší počítačovou síť
                    pro prodej vstupenek..."
}

Generování řetězce SPAYD – Parametry příkazu v ČR

URL: ${SERVER}/generator/czech/string
Metoda: GET
Parametry:

Odpověď v negativním případě:

Odpověď v pozitivním případě:

Generování souboru SPAYD – Parametry příkazu v ČR

URL: ${SERVER}/generator/czech/spayd
Metoda: GET
Parametry:

Odpověď v negativním případě:

Odpověď v pozitivním případě:

Generování QR kódu SPAYD – Parametry příkazu pro ČR

URL: ${SERVER}/generator/czech/image
Metoda: GET
Parametry:

Odpověď v negativním případě:

Odpověď v pozitivním případě:

HTTP kód	Popis odpovědi, příklad
200 – OK	Tělo odpovědi obsahuje QR kód (application/png), který obsahuje řetězec SPAYD, např.:

Generování řetězce SPAYD – základní parametry

URL: ${SERVER}/generator/string
Metoda: GET
Parametry:

Odpověď v negativním případě:

Odpověď v pozitivním případě:

Generování souboru SPAYD – základní parametry

URL: ${SERVER}/generator/spayd
Metoda: GET
Parametry:

Odpověď v negativním případě:

Odpověď v pozitivním případě:

Generování QR kódu SPAYD – základní parametry

URL: ${SERVER}/generator/image
Metoda: GET
Parametry:

Odpověď v negativním případě:

Odpověď v pozitivním případě:

HTTP kód	Popis odpovědi, příklad
200 – OK	Tělo odpovědi obsahuje QR kód (image/png), který obsahuje řetězec SPAYD, např.: