Atjaunots 08. novembris 2022

Kādā veidā jānoformē API pieprasījumi?

https://username:password@hostname:port/api/1/IVVc

Šis ir vienkāršākais parauga pieprasījums par konkrētu uzņēmumu un konkrētu reģistru, kur
– “username” ir lietotājvārds no Personu reģistra;

-“password” ir lietotāja parole

– “hostname” ir servera IP adrese;
– “port” ir servera https ports;
– “api” ir obligātā pieprasījuma daļa kā simbolu virkne;
– “1” ir uzņēmuma kods uzņēmumu reģistrā;
– “IVVc” ir reģistra nosaukums (dotajā piemērā “Realizācijas rēķini”).

Šis pieprasījums izvelk visus pārdošanas rēķinus no uzņēmuma 1. Ja vēlies līdzīgā veidā iegūt informāciju, piemēram, par bāzes valūtām, tad ir jāizmanto pieprasījums:

https://username:@hostname:port/api/1/BaseCurBlock

DATU FORMĀTS
Pieprasījumu datu formāti un saņemto datu formāti ir vienādi un stingri fiksēti:
– kā decimāldaļas atdalītājs ir jāizmanto “.” (punkts);
– tūkstošu atdalītājs netiek izmantots;
– datumi ir ISO formātā GGGG-MM-DD (gads, mēnesis, diena);
-? (jautājuma zīme) tiek ievadīta pēc reģistra definēšanas, ja ir vēlēšanās precizēt filtrus;
– & tiek izmantots starp dažādiem filtriem.

PARAMETRI
Reālās parametru vērtības, kas tiek izmantotas pieprasījumos (piemēram, izmantotā atslēga/ID un diapazons, servera versija u.c.), rezultātos tiek uzrādītas kā datu lauku atribūti (“data tag”). Tālāk ir sniegti parametru piemēri.

sort – šķirošanas parametrs sakārto saņemtās kartes pēc norādītā datu lauka. Pieprasījuma rezultātos tiek atspoguļots arī izmantotā indeksa nosaukums. Šķirošanu ir iespējams veikt tikai pēc kartes galvenes laukiem. Vienlaicīgi ir iespējams veikt šķirošanu tikai pēc viena lauka pie nosacījuma, ka šim nolūkam ir piemērots indekss. Ja piemērota indeksa nav, tad pieprasījums rezultātus nesniedz. Lauka nosaukuma gadījumā ir svarīgi lielie un mazie burti. Piemērs (pieprasījums no Realizācijas rēķinu reģistra, šķirošana veikta pēc klienta koda):

https://username:@hostname/api/1/IVVc?sort=CustCode

range – diapazona parametra izmantošanai ir jāizmanto arī šķirošanas parametrs. Diapazons veic pieprasījumu tikai attiecībā uz tām kartēm, kurās šķirojamā lauka vērtība ietilpst norādītajā diapazonā. Rezultātos tiek iekļautas arī tās vērtības, kas vienādas ar diapazona sākuma un beigu vērtībām. Diapazona sākuma un beigu vērtības atdala ar “:” (kolu). Ir atļauti arī tādi pieprasījumi, kuros ir norādīta tikai diapazona sākuma vai beigu vērtība. Ja pieprasījumā tiek izmantota tikai viena konkrēta vērtība (bez kola), tad tiek izsniegtas tikai tās kartes, kas atbilst šai konkrētajai vērtībai.

1. piemērs (tiek izsniegti Realizācijas rēķini, kuros klientu kodi ir diapazonā no 10101 līdz 10104):
https://username:@hostname/api/1/IVVc?sort=CustCode&range=10101:10104

2. piemērs (tiek izsniegti Realizācijas rēķini, kuros klientu kodi ir diapazonā no 10104 līdz pēdējam klientam):
https://username:@hostname/api/1/IVVc?sort=CustCode&range=10104:

3. piemērs (tiek izsniegti pārdošanas rēķini, kuros ir tikai klienta kods 10104):
https://username:@hostname/api/1/IVVc?sort=CustCode&range=10104

Diapazona parametrs ir ātrs, jo tas izmanto indeksu.

fields – lauku parametrs nosaka, kuri lauki tiek iekļauti rezultātā. Laukus atdala ar komatiem. Ja parametrs nav norādīts, tad rezultātos tiek ņemta informācija no visiem laukiem. Ja kartes/dokumenta galvenē un rindās ir tāda paša nosaukuma lauks, tad rezultātos tiek iekļauta informācija no abiem. Ja netiek pieprasīts neviens rindu lauks, tad rezultātos netiek atspoguļota nekāda rindu informācija (rindu numuri u.tml.).

Piemērs (tiek izsniegti Realizācijas rēķini tikai ar rēķina numuru:
https://username:@hostname/api/1/IVVc? fields=SerNr

filtrs – Datus var filtrēt, izmantojot šo parametru. Filtrs ir ievērojami lēnāks nekā diapazons, jo tas neizmanto indeksus un veic meklēšanu visās kartēs. Izmantojot diapazona parametru, filtrs iziet cauri tikai tām kartēm, kuras atrodas diapazonā. Tāpēc ir ieteicams izmantot pēc iespējas precīzāku diapazona iestatījumu un citus filtrus.

Piemērs:
https://username:@hostname/api/1/IVVc?filter.CustCode=10104

• Uz katru lauku drīkst izmantot tikai vienu filtru
• Izmantojot dažādus laukus, var izmantot vairākus filtrus
• Līdzīgā veidā filtri var izmantot vērtību diapazonus, arī tad, ja ir noteikts tikai diapazona sākums vai beigas.
• Filtri darbojas tikai ar karšu/dokumentu galvenes datu laukiem.
• Filtrēšana saraksta laukos (piemēram, Objektu gadījumā) tiek veikta visas simbolu virknes apmērā. Piemēram: filtrs.Objects = AB neietvers rezultātu “AB, D10101”

Piemērs (tiek izsniegti rēķini, kuru gala summa ir diapazonā no 100 līdz 1000 un kuros klientu kodi ir diapazonā no 10100 līdz 10200):
https://username:@hostname/api/1/IVVc?filter.CustCode=10100:10200&Sum4=100:1000

offset and limit – ja pieprasījuma rezultāts ir lielāks nekā API lietotājs var apstrādāt viena pieprasījuma ietvarā, tad rezultātus var sadalīt mazākās daļās. “offset” izlaiž pieprasījuma rezultātos noteiktu skaitu dokumentu. “limit” ierobežo kopējo skaitu pieprasījuma rezultātos.

Piemērs (tiek izsniegti pirmie 15 Realizācijas rēķini ar 3 dažādiem pieprasījumiem):
https://username:@hostname/api/1/IVVc?offset=0&limit=5
https://username:@hostname/api/1/IVVc?offset=5&limit=5
https://username:@hostname/api/1/IVVc?offset=10&limit=5

“offset” un “limit” var izmantot kopā ar visiem citiem parametriem.

updates_after – izsniedz visas kartes/dokumentus, kas ir atjaunoti pēc noteiktā kārtas numura. Kārtas numurs tiek izsniegts katra pieprasījuma gadījumā (sequence=”x”), un vēlāk to var izmantot ar parametru “updates_after”.

Piemērs:
https://username:@hostname/api/1/IVVc?updates_after=5000

deletes_after – izsniedz visus ierakstis, kas ir dzēsti pēc noteiktā kārtas numura. Kārtas numurs tiek izsniegts katra pieprasījuma gadījumā, un vēlāk to var izmantot ar parametru “deletes_after”.

Piemērs:
https://username:@hostname/api/1/IVVc?deletes_after=5000

____

REST API vers.2 APRAKSTS ANGĻU VALODĀ