Protokol REST (KS webAPI)

Z Prirucky
Verze z 10. 3. 2025, 12:11, kterou vytvořil Pavelm (diskuse | příspěvky) (založena nová stránka s textem „ <h1>KS REST WebAPI</h1> <h2>Základní informace</h2> Komplexní API pro správu dat souhrnů údajů, zaměstnanců a autentizaci uživatelů. Umožňuje vkládání, aktualizaci, výběr a mazání dat v různých souhrnech údajů na základě specifikovaných kritérií a operací prováděných prostřednictvím HTTP metod. <!-- AUTENTIZACE --> <h2 id="access">Autentizace k API KS Program</h2> <ol>…“)
(rozdíl) ← Starší verze | zobrazit aktuální verzi (rozdíl) | Novější verze → (rozdíl)

KS REST WebAPI

Základní informace

Komplexní API pro správu dat souhrnů údajů, zaměstnanců a autentizaci uživatelů. Umožňuje vkládání, aktualizaci, výběr a mazání dat v různých souhrnech údajů na základě specifikovaných kritérií a operací prováděných prostřednictvím HTTP metod.

Autentizace k API KS Program

  1. Zabezpečení protokolu

    Všechny dotazy na API musí být zasílány prostřednictvím zabezpečeného protokolu HTTPS.

  2. Přístupová oprávnění

    Uživatel musí mít povolení k užívání API, které mu uděluje administrátor. K tomu je nezbytné mít vygenerováno jméno a heslo k API.

  3. Autentizace

    Pro autentizaci je třeba odeslat na adresu .../KSAsServer/WebService/WebAPI/rest/users/authenticate JSON body s údaji "Username" a "Password". Pokud jsou tyto údaje správné, obdržíte token, který je nutný pro používání API po určitou dobu. Token i jeho platnost jsou vráceny v těle odpovědi.

  4. Použití tokenu

    Při každém volání API ,mimo autentizaci, je třeba zaslat platný token jedním ze dvou způsobů:

    • V HEADER

      Plain: 

      Authorization -   eyJ0eXAwibmFtZSI6InBhdmVIuMDGtBE1GxcdkwUuTTLDL4&
      Bearer: 
      Authorization -   Bearer eyJ0eXAwibmFtZSI6InBhdmVIuMDGtBE1GxcdkwUuTTLDL4&

    • V URI 
      GET /KSAsServer/WebService/WebAPI/rest/KmenoveUdaje/Jmeno/Karel?<strong>token=eyJ0eXAwibmFtZSI6InBhdmVIuMDGtBE1GxcdkwUuTTLDL4&</strong>

    Způsob HEADER je preferován před URI.

Příklad:

Požadavek

POST /KSAsServer/WebService/WebAPI/rest/user/authenticate

body:
{
    "Username": "jmeno",
    "Password": "heslo"
}

Odpověď

{
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Created",
    "ResponseDatetime": "/Date(1720705997339+0200)/",
    "StatusCode": 201,
    "Token": "jkdsjflsdfjsdfklsjdflskdfjs.6tQew",
    "ValidTo": "/Date(1720715997000+0200)/"
}

Metody

Veškerá dokumentakce k metodám: https://prirucky.ksprogram.cz/index.php?title=Metody_(KS_webAPI).

Parametry

  • Request header

    Content-Type - application/raw Accept - application/json

  • Items

    Vyplňuje se v případě volání metody GET/POST. Předává se seznam <a href="https://prirucky.ksprogram.cz/index.php?title=Polo%C5%BEky_(KS_webAPI)">položek</a>, které budou v návratové datové struktuře, na které má uživatel oprávnění. Jednotlivé položky se oddělují čárkou. Pokud bude v parametru předáno více položek, vrací se návratová datová struktura, která obsahuje všechny položky uvedené v parametru oddělené čárkami. Pokud bude zadáno více 'Item' v parametru, bude vrácena množina údajů odpovídající průniku záznamů jednotlivých 'Item'. V případě nezadání paramteru, vrátí všechny položky, na které má uživatel oprávnění.

  • <a href="https://prirucky.ksprogram.cz/index.php?title=JsonSearchCriteria">JsonSearchCriteria</a>
  • <a href="https://prirucky.ksprogram.cz/index.php?title=JsonOptions">JsonOptions</a>
  • <a href="#access">Token</a>

Proměnné cesty

  • aItemGroup

    (Required) Název souhrnu údajů. Parametr {aItemGroup} je nutno zaměnit za reálný souhrn údajů. Předává se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').

GET - Vrací data souhrnu údajů podle zadaného názvu souhrnu.

Povinné parametry: Token, aItemGroup.

Volitelné parametry: JsonSearchCriteria, Items, JsonOptions.

Příklad:

Vrátí data ze souhrnu údajů "KmenoveUdaje", kde OsCislo <= 100.

Požadavek

GET /KSAsServer/WebService/WebAPI/rest/KmenoveUdaje/?token=12asd16a5sda1s32d&Item=Jmeno,Prijmeni,OsCislo,RodneCislo&JsonSearchCriteria=[{ 'Item': 'OsCislo', 'Operator': '<=', 'Value': 100 }]

Odpověď

{
    "Data": "[{\"OsCislo\":36,\"Titul\":null,\"Jmeno\":\"Miroslav\",\"Prijmeni\":\"Nový\",\"RodneCislo\":\"123456789\"...}],
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Data nalezena.",
    "ResponseDatetime": "/Date(1720696754982+0200)/",
    "StatusCode": "200"
}

GET - Vyhledá zaměstnance ze skupiny údajů 'KmenoveUdaje' podle zadaného osobního čísla.

Povinné parametry: Token, aItemGroup, aOsCislo.

Volitelné parametry: JsonSearchCriteria, Items, JsonOptions.

Příklad:

Vrátí data ze souhrnu údajů "KmenoveUdaje", kde OsCislo = 1. Vrátí sloupce OsCislo, Titul, Jmeno, Primeni, RodneCislo

Požadavek

GET /KSAsServer/WebService/WebAPI/rest/KmenoveUdaje/1?token=eyJ0eXAiOIiwi7_GcdkwUuTTLDL4&items=OsCislo, Titul, Jmeno, Prijmeni, RodneCislo

Odpověď

{
    "Data": "[{\"OsCislo\":1,\"Titul\":\"Ing.\",\"Jmeno\":\"Pavel\",\"Prijmeni\":\"Hovorka\",\"RodneCislo\":\"581227411\"}]",
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Data nalezena.",
    "ResponseDatetime": "/Date(1720766282434+0200)/",
    "StatusCode": "200"
}

GET - Vrací data, kde údaj 'aItem' má hodnotu 'aValue' v rámci zadaného souhrnu údajů 'aItemGroup'.

Povinné parametry: Token, aItemGroup, aItem, aValue.

Volitelné parametry: JsonSearchCriteria, Items, JsonOptions.

Příklad:

Vrátí data ze souhrnu údajů "KmenoveUdaje", kde Jmeno = Pavel.

Požadavek

GET /KSAsServer/WebService/WebAPI/rest/KmenoveUdaje/Jmeno/Pavel?token=eyJ0eXAwibmFtZSI6InBhdmVIuMDGtBE1GxcdkwUuTTLDL4&

Odpověď

{
    "Data": "[{\"OsCislo\":1,\"Titul\":\"Ing.\",\"Jmeno\":\"Pavel\",\"Prijmeni\":\"Hovorka\",\"RodneCislo\":\"581227411\"},
            {\"OsCislo\":18,\"Titul\":null,\"Jmeno\":\"Pavel\"...}]",
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Data nalezena.",
    "ResponseDatetime": "/Date(1720766630099+0200)/",
    "StatusCode": "200"
}


POST - Vkládá data do zadaného souhrnu údajů.

Metoda InsertData zapisuje data do databáze KS mzdy.

Povinné parametry: Token, aItemGroup, JsonChangeData (data v těle požadavku).

Příklad:

Vloží data z body požadavku do souhrnu údajů "KmenoveUdaje".

Požadavek

POST /KSAsServer/WebService/WebAPI/rest/KmenoveUdaje?token=eyJ0eXAiOiJKV1QtL2BDA7_GcdkwUuTTLDL4&

Body:
[
    {
        "IdPodniku": "1",
        "Jmeno": "Karel",
        "Prijmeni": "Nový",
        "RodneCislo": "9710085892",
        "MistoNarozeni": "Vsetín",
        "StatNar": "CZ",
        "StPrisl": "203",
        "RodinStav": "2",
        "TrCislo": "100",
        "PscTrv": "75501",
        "MistoTrv": "Vsetín",
        "KmenStr": "1",
        "DatumNastupu": "2019-01-01"
    }
]

Odpověď

{
    "Data": "[{\"OsCislo\": 95967,\"IdPodniku\": 1,\"Jmeno\": \"Karel\",\"Prijmeni\": \"Nový\""...}]",
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Vybraná data byla vložena.",
    "ResponseDatetime": "/Date(1720767043837+0200)/",
    "StatusCode": "201"
}

PUT / UPDATE - Aktualizuje data do zadaného souhrnu údajů.

Povinné parametry: Token, aItemGroup, JsonChangeData (data v těle požadavku), JsonSearchCriteria.

Příklad:

Aktualizuje data v souhrnu údajů "Kontakty", kde Hodnota = 222 222 222, na Hodnota = 111 111 111.

Požadavek

PUT /KSAsServer/WebService/WebAPI/rest/Kontakty?token=eyJ0eXAiOiJKV1QiLaW_GcdkwUuTTLDL4&JsonSearchCriteria=[{ "Item": "Hodnota", "Operator": "=", "Value": "222 222 222"}]

Body:
[
    {
        "Hodnota": "111 111 111"
    }
]

Odpověď

{
    "Data": "",
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Vybraná data byla aktualizována.",
    "ResponseDatetime": "/Date(1721030337638+0200)/",
    "StatusCode": "204"
}

DELETE - Smaže data v zadaném souhrnu údajů.

Metoda DELETE smaže data v databázi KS mzdy.

Povinné parametry: Token, aItemGroup, JsonSearchCriteria.

Příklad:

Smaže data v souhrnu údajů "Kontakty", kde Hodnota = 111 111 111

Požadavek

DELETE KSAsServer/WebService/WebAPI/rest/Kontakty?token=eyJ0eXAiOiJKV1QiLCk&JsonSearchCriteria=[{ "Item": "Hodnota", "Operator": "=", "Value": "111 111 111"}]

Odpověď

{
    "Data": "",
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Vybraná data byla smazána.",
    "ResponseDatetime": "/Date(1721030823993+0200)/",
    "StatusCode": "204"
}
Citováno z „http://prirucky.ksprogram.cz/index.php?title=Protokol_REST_(KS_webAPI)&oldid=47927“