API dla SOD > REST API

| Drukuj

REST API

Symfonia Obieg Dokumentów udostępnia API (Application Programming Interface), dzięki któremu jesteśmy w stanie przeprowadzać podstawowe czynności. Usługa jest zabezpieczona tokenem autoryzującym (Bearer Token), który uzyskujemy przy logowaniu za pomocą nazwy użytkownika i hasła, a następnie dodajemy nagłówek wg dokumentacji, gdzie {{TOKEN}} zamieniamy na token otrzymany po zalogowaniu.

 

Authorization: Bearer {{TOKEN}}

 

Ważną uwagą jest fakt że po zalogowaniu token można użyć zarówno do REST/v1 oraz REST/custom.

 

Lista metod

Pełna dokumentacja endpointów znajduje się pod tym linkiem.

 

Schemat interakcji z API

Logowanie

Na tym etapie należy zalogować się do systemu za pomocą tego endpointu.

 

hmtoggle_plus1        cURL

curl --location --request POST 'https://localhost/api.php/REST/v1/login' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "username": "",
    "password": "",
    "edok_entity": ""
}'

hmtoggle_plus1        PHP cURL

$curl = curl_init();

 

curl_setopt_array($curl, array(

  CURLOPT_URL => "https://localhost/api.php/REST/v1/login",

  CURLOPT_RETURNTRANSFER => true,

  CURLOPT_ENCODING => "",

  CURLOPT_MAXREDIRS => 10,

  CURLOPT_TIMEOUT => 0,

  CURLOPT_FOLLOWLOCATION => true,

  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,

  CURLOPT_CUSTOMREQUEST => "POST",

  CURLOPT_POSTFIELDS =>"{\n    \"username\": \"\",\n    \"password\": \"\",\n    \"edok_entity\": \"\"\n}",

  CURLOPT_HTTPHEADER => array(

    "Content-Type: application/json",

    "Content-Type: text/plain"

  ),

));

 

$response = curl_exec($curl);

 

curl_close($curl);

echo $response;

hmtoggle_plus1        HTTP

POST /login HTTP/1.1

Host: https://localhost/api.php/REST/v1

Content-Type: application/json

Content-Type: text/plain

 

{

    "username": "",

    "password": "",

    "edok_entity": ""

}

 

Otrzymamy następującą odpowiedź:

{
    "token": "dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ==",
    "refreshToken": "V_example_ENQG9U_example_NvIj9YVVM7eUANNTVKCnNFO_example_QhI3whc1BPJDcxSEtPVH_example_="
}

Token posłuży nam do dalszego autentykacji, natomiast refresh_token służy do odświeżenia tego wcześniejszego tokenu jeżeli nam sesja wygasła.

 

Token token jest ważny 1 dzień, natomiast refreshToken jest ważny 6 miesięcy.

 

Wykonywanie dostępnych operacji

Sprawdzenie wersji systemu

hmtoggle_plus1        cURL

curl --location --request GET 'http://localhost/api.php/REST/v1/system/version' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ=='

hmtoggle_plus1        PHP cURL

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "http://localhost/api.php/REST/v1/system/version",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ=="
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

hmtoggle_plus1        HTTP

GET /system/version HTTP/1.1
Host: http://localhost/api.php/REST/v1
Content-Type: application/json
Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ==

 

Odpowiedź

{
    "version": "7.18.0"
}

 

Utworzenie dokumentu typu plik

hmtoggle_plus1        cURL

curl --location --request POST 'http://localhost/api.php/REST/v1/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ' \
--data-raw '{
    "dctptp": "Other",
    "prtpid": 6,
    "prc_id": 1,
    "dscrpt":"Nowy dokument z pliku",
    "contid": 2
}'

hmtoggle_plus1        PHP cURL

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'http://localhost/api.php/REST/v1/documents',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "dctptp": "Other",
    "prtpid": 6,
    "prc_id": 1,
    "dscrpt":"Nowy dokument z pliku",
    "contid": 2
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ',
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

hmtoggle_plus1        HTTP

POST /api.php/REST/v1/documents HTTP/1.1
Host: localhost
Content-Type: application/json
Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ
Content-Length: 114
{
    "dctptp": "Other",
    "prtpid": 6,
    "prc_id": 1,
    "dscrpt":"Nowy dokument z pliku",
    "contid": 2
}

 

Odpowiedź

{
    "data": {
        "doc_id": 68
    }
}

 

Dodanie załącznika

Załącznik wyślemy w postaci JSON. Istnieją inne sposoby (np. binarnie) co omawiamy w dalszych rozdziałach.

 

hmtoggle_plus1        cURL

curl --location --request POST 'http://localhost/api.php/REST/v1/documents/68/attachments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 360b396ede057e63505a1aa09a912bdc0ee37ec60b01595ea8b2fb343d087177' \
--header 'Cookie: PHPSESSID=2upi0ag93v3mmd8mbmralo9b17' \
--data-raw '{
    "attachments": [
        {
            "fileName":"hacker2.png",
            "transferEncoding":"base64",
            "fileContent": "<content file in encode base64>"  
        }
    ]
}'

hmtoggle_plus1        PHP cURL

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'http://localhost/api.php/REST/v1/documents/68/attachments',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "attachments": [
        {
            "fileName":"hacker2.png",
            "transferEncoding":"base64",
            "fileContent": "<content file in encode base64>"  
        }
    ]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer 360b396ede057e63505a1aa09a912bdc0ee37ec60b01595ea8b2fb343d087177',
    'Cookie: PHPSESSID=2upi0ag93v3mmd8mbmralo9b17'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

hmtoggle_plus1        HTTP

POST /api.php/REST/v1/documents/68/attachments HTTP/1.1
Host: localhost
Content-Type: application/json
Authorization: Bearer 360b396ede057e63505a1aa09a912bdc0ee37ec60b01595ea8b2fb343d087177
Cookie: PHPSESSID=2upi0ag93v3mmd8mbmralo9b17
Content-Length: 11710
{
    "attachments": [
        {
            "fileName":"hacker2.png",
            "transferEncoding":"base64",
            "fileContent": "<content file in encode base64>"  
        }
    ]
}

 

Odpowiedź

{
    "data": {
        "fileid": [
            71
        ]
    }
}

 

Wylogowanie się

W celu zakończenia połączenia (sesji) należy się wylogować przez api za pomocą tego endpointu

 

hmtoggle_plus1        cURL

curl --location --request GET 'http://localhost/api.php/REST/v1/logout' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ=='

hmtoggle_plus1        PHP cURL

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "http://localhost/api.php/REST/v1/logout",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ=="
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

 

hmtoggle_plus1        HTTP

GET /logout HTTP/1.1
Host: http://localhost/api.php/REST/v1
Content-Type: application/json
Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ==

 

Odpowiedź

{
    "result": true
}

 

Załączniki

Wysyłanie załączników

Załączniki możemy wysyłać do REST API na dwa sposoby:

Link do dokumentacji przykładowego endpointu.

 

BINARY

hmtoggle_plus1        cURL

curl --location --request POST 'http://localhost/api.php/REST/v1/events/1/attachments' \
--header 'Content-Type: multipart/form-data; boundary=<calculated when request is sent>' \
--header 'Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ==' \
--form '=@/home/user/Obrazy/BingWallpaper/20200522-ReichenbachFalls_EN-US9352987746_1920x1080.jpg'

hmtoggle_plus1        PHP cURL

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "http://localhost/api.php/REST/v1/events/1/attachments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => array('plik1'=> new CURLFILE('/home/pkuznik/Pobrane/Open_Sans.zip')),
  CURLOPT_HTTPHEADER => array(
    "Authorization: dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ"
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

hmtoggle_plus1        HTTP

POST /api.php/REST/v1/events/1/attachments HTTP/1.1
Host: localhost
Authorization: dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQContent-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="plik1"; filename="Open_Sans.zip"
Content-Type: application/zip
(data)
----WebKitFormBoundary7MA4YWxkTrZu0gW

 

JSON

hmtoggle_plus1        cURL

curl --location --request POST 'http://localhost/api.php/REST/v1/events/1/attachments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ==' \
--data-raw '[{
    "fileName":"20200522-ReichenbachFalls_EN-US9352987746_1920x1080.jpg",
    "transferEncoding":"base64",
    "fileContent":"<content file in encode base64>"
}]'

hmtoggle_plus1        PHP cURL

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "http://localhost/api.php/REST/v1/events/1/attachments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>"[{\n    \"fileName\":\"20200522-ReichenbachFalls_EN-US9352987746_1920x1080.jpg\",\n    \"transferEncoding\":\"base64\",\n    \"fileContent\":\"<content file in encode base64>\"\n}]",
  CURLOPT_HTTPHEADER => array(
    "Authorization: dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ",
    "Content-Type: text/plain"
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

hmtoggle_plus1        HTTP

POST /api.php/REST/v1/events/1/attachments HTTP/1.1
Host: localhost
Authorization: dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ
Content-Type: text/plain
[
  {
    "fileName":"20200522-ReichenbachFalls_EN-US9352987746_1920x1080.jpg",
    "transferEncoding":"base64",
    "fileContent":"<content file in encode base64>"
  }
]

 

Pobieranie załączników

Załącznik możemy pobrać na dwa sposoby: Link do dokumentacji przykładowego endpointu.

 

BINARY

curl --location --request GET 'http://localhost/api.php/REST/v1/events/1/attachments/1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ==' \
--header 'Accept: application/octet-stream'

 

JSON

curl --location --request GET 'http://localhost/api.php/REST/v1/events/1/attachments/1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer dX_example_JVHYiZ3xJTyotezpk_example_1BxKm4idTcge1p8VE08_example_1dZTk97RXUiTW15RnNuCQ==' \
--header 'Accept: application/json'

 

Wyszukiwarki

W systemie udostępniono endpointy, za pomocą których można przeszukiwać, filtrować całe zbiory danych.

Przykład wszyscy klienci z alarmem (GET \contacts): &alarm_=true

 

Operatory tekstowe

W każdym endpoincie możliwe jest szukanie po każdej kolumnie, która jest zwracana w odpowiedzi. &pole1=fraza

 

Można wyszukiwać wyłącznie po kolumnach, które zwracane są w głównej encji.

 

/contacts?symbol=CAD

 

W przypadku kiedy chcemy wyszukać po frazie składającej się z dwóch słów np. „sąd rejonowy”, wtedy słowa odzielamy znakiem plusa.

 

/contacts?name_1-ilike[]=sąd+rejonowy

 

Aby wyszukać klientów o konkretnych statusach, wtedy na końcu nazwy klucza dodajemy nawiasy kwadratowe. Całość zostanie potraktowana jako tablicę w SQLu.

 

/contacts?tpstid[]=23&tpstid[]=26&tpstid[]=30

 

Aby móc szukać po niepełnych fraz i słów, należy użyć jednej ze specjalizowanych funkcji poprzez doklejenie do jej nazwy rozszerzenia:

•-not – Negacja

Przykład: QUERY: &pole1-not=fraza

Wynikowy SQL: pole1 != 'fraza'

•-like – Prosty like

Przykład: QUERY &pole1-like=fraza%

Wynikowy SQL: pole1 like 'fraza%'

•-notlike – Negacja do powyższego like

Przykład: QUERY &pole1-notlike=fraza%

Wynikowy SQL: pole1 not like 'fraza%'

•-ilike – Wyszukiwanie ciągu porównując go do początku każdego wyrazu (działa jak systemowe lookupy)

Przykład: QUERY &pole1-ilike=fraza

Wynikowy SQL: pole1 ~* E'(^| |-|\\'|")fraza'

•-notilike – negacja do powyższego

Przykład: QUERY &pole1-ilike=fraza

Wynikowy SQL: pole1 !~* E'(^| |-|\\'|")fraza'

 

Jeżeli z jedną kolumną chcemy zrobić kilka porównań, wtedy należy użyć typu tablicowego tzw. do nazwy zmiennej dodać kwadratowe nawiasy [].

&pole1-ilike[]=fraza1&pole1-ilike[]=fraza2

 

Przykład:

/contacts?name_1-ilike[]=szpital&name_1-ilike[]=kliniczny

 

Powyższe funkcje działają tylko dla kolumn typu string.

 

Operacje daty

Możemy również dodać filtr, który zwróci nam rekordy z odpowiedniego okresu, do tego należy wykorzystać następujące funkcje:

•-start początek zakresu

•-end koniec zakresu

 

Powyższe funkcje można ze sobą łączyć:

•Użycie -start Przykład: QUERY pole1-start=2020-11-01

Wynikowy SQL: pole1 >= '2020-11-01'

•Użycie -end Przykład: QUERY pole1-end=2020-11-01

Wynikowy SQL: pole1 <= '2020-11-01'

•Użycie -start i -end Przykład: QUERY pole1-start=2020-11-01&pole1-end=2020-11-30

Wynikowy SQL: pole1 BETWEEN '2020-11-01' AND '2020-11-30'

 

Operatory matematyczne

System udostępnia także zbiór funkcji, które możemy wykorzystać do porównania liczb. Wywołanie bez funkcji &pole1=1 jest jednoznaczne z zapisem SQL pole1 = 1.

•-not – Negacja

Przykład: QUERY: &pole1-not=1

Wynikowy SQL: pole1 != 1

•-gt – jednoznaczne z pole1 > 2

Przykład: QUERY: &pole1-gt=2 SQL: pole1 > 2

•-gte – jednoznaczne z pole1 >= 2

Przykład: QUERY: &pole1-gte=2 SQL: pole1 >= 2

•-lt – jednoznaczne z pole1 < 2

Przykład: QUERY: &pole1-lt=2 SQL: pole1 < 2

•-lte – jednoznaczne z pole1 <= 2

Przykład: QUERY: &pole1-lte=2 SQL: pole1 <= 2

 

Dodatkowe operatory

W dokumentacjach tych endpointów udostępniono następujące parametry QUERY:

•_fields (string) – Nazwy pól rozdzielone przecinkiem, które mają zostać zwrócone w odpowiedzi.

Przykład: _fields=pole1,pole2,pole3

/contacts?_fields=contid,name_1,email_

 

•_filter (string) – Modyfikator opcjonalny złożenia warunków, które zostały przekazane w sekcji query. Jeśli tego parametru nie podasz, to wszystkie warunki zostaną złożone ANDem. W tym parametrze możesz używać następujących wartości: () OR AND <nazwy pól, których używasz w query>

Przykład 1: &_filter=pole1-OR-pole2

Lista klientów zawierających w nazwie (name_1 lub name_2) słowo poznań

/contacts?_filter=name_1-or-name_2&name_1-ilike=poznań&name_2-ilike=poznań

Przykład 2: &_filter=(pole1-OR-pole2)AND-pole3

Lista klientów zawierających w nazwie (name_1 lub name_2) słowo poznań oraz utworzonych od stycznia 2020 roku

/contacts?_filter=(name_1-or-name_2)and-adddat&name_1-ilike=poznań&name_2-ilike=poznań&adddat-start=2020-01-01

 

•_sort (string) – Nazwy pól, po których ma odbyć się sortowanie ASC, Dla DESC do nazwy pola doklejamy prefix ‚-‚

Przykład 1: &_sort=pole1 – sortowanie rosnące

/contacts?_sort=name_1

Przykład 2: &_sort=-pole1 – sortowanie malejące

/contacts?_sort=-name_1

 

•_limit (int) – Ile rekordów ma zostać zwróconych.

/contacts?_limit=100

 

•_offset (int) – Od którego rekordu mają zostać zwracane wyniki.

/contacts?_offset=100