Kuidas API POST päringuid vormistada?

Uuendatud 09. juuli 2024

Kuidas API POST päringuid vormistada?

Selleks, et teha uusi sisestusi Standard Books’i registritesse kasutatakse POST funktsionaalsust. Andmete lisamine erineb andmete pärimisest formaadi poolest. Lisamine toimub API URL’i kasutades.
Andmete lugemisest GET päringutega loe SIIT

POST PÄRINGU ELEMENDID
URL, millega postitatakse uusi sisestusi Standard Books keskkonda sisaldab järgnevaid elemente:
Kasutaja – Standard Books kasutaja, millel on lisatud kasutajagrupiga õigus toimingule „RestAPI“
Parool – Eelnevalt kirjeldatud kasutaja parool.
IP – Standard Books serveri IP.
Port – Standard Books serveri HTTP/HTTPS port.
Funktsioon – Tähistab funktsiooni, mida kasutatakse. Rest API puhul on tegemist alati „api“-ga.
Ettevõte – Standard Books serveris paikneva ettevõtte number. Leitad Standard Booksis Ettevõtete registrist.
Register – Tähistab registrit, kuhu soovitakse uus kaart sisestada.
Välja kirjeldus – Tähistab välja täitmisfunktsiooni Set_field, välja tehnilist nimetust ja välja sisestust.
Maatriksi välja kirjeldus – Tähistab maatriksi välja täitmisfunktsiooni Set_row_field, välja tehnilist nimetust ja välja sisestust.

Eraldajad
Koolon [:] – Kasutatakse elementide Kasutaja ja Parool, IP ja Port vahel
[@] – Kasutatakse elementide Parool ja IP vahel.
Küsimärk [?] – Kasutatakse elementide Register ja Välja kirjeldus vahel
Võrdusmärk [=] – Kasutatakse elementide Välja kirjeldus ja välja sisestuse vahel
Ampersand [&] – Kasutatakse, kui soovitakse kirjeldada rohkem kui 1 välja sisestust.

Väljade kirjeldused URL’is
Selleks, et Rest API kasutamisel andmeid Standard Booksi kirjutada, tuleb kirjeldada ära väljad. URL’i lõpus on võimalik defineerida kaardi kõikide väljade informatsioon. Kaardi ja maatriksi väljade puhul näeb see välja erinev.

Kaardi väli:
Set_field.[välja tehniline nimetus]=[välja sisestus]

Maatriksi väli:
Set_row_field.[maatriksi rea number]. [välja tehniline nimetus]=[välja sisestus]

NB! Maatriksi rea numbrid algavad nullist (0) ehk 0 on esimene rida, 1 on teine rida jne.

Väljade kirjeldused saab URL’is üksteise järgi lisada kasutades eraldajat [&].

Näide:

curl -X POST ‘http://SJ:@127.0.0.1:8080/api/1/IVVc?set_field.CustCode=001&set_row_field.0.ArtCode=10101&set_row_field.0.Quant=3’

Antud päringu vastuse formaat on järgnev:

<data register=”IVVc” sequence=”9693″ url=”/api/1/IVVc/10000014″ systemversion=”8.5.38.66″

<IVVc>

<SerNr>10000010</SerNr>

<InvDate>2021-05-30</InvDate>

<CustCode>001</CustCode>

<Math></Math>

<PayDate>2021-06-29</PayDate>

<Addr0>Against All Odds Trading Co</Addr0>

…

<rows>

<row rownumber=”0″>

<stp>1</stp><ArtCode>10101</ArtCode>

<Quant>3</Quant>

<Price>25.00</Price>

<Sum>71.25</Sum>

…

</row rownumber=”0″>

…

</rows>

…

</IVVc>

</data>

Eelnevalt kirjeldatud päring loob Standard Books’i uue müügiarve, millele on määratud klient koodiga 001, lisab müügiarvele ühe rea, kasutades artiklikoodi 10101, kogusega 3.

Juhul kui on vajalik kasutada muid tähiseid, kui numbrid, kasutadage ASCII encoding’t.

Näide:
curl -X POST ‘http://SJ:@127.0.0.1:8080/api/1/CUVc?set_field.Code=301&set_field.Name=Test%20%26%20Co’

Antud päring loob uue kontaktikaardi koodiga 301 ja määrab kontakti nimeks „Test & Co.“

Alternatiiv näide:

curl -X POST –data-urlencode “set_field.Name=Test & Co” ‘http://SJ:@127.0.0.1:8080/api/1/CUVc?set_field.Code=301’

PATCH

Selle jaoks, et muuta olemasolevaid kirjeid Standard Books’is tuleb kasutada PATCH päringu funktsionaalsust. Päringu ülesehitus ja syntax on sama, mis POST päringu puhul.

Näide:

curl -X PATCH ‘http://SJ:@127.0.0.1:8080/api/1/IVVc/10000014?set_row_field.0.Quant=100’

PATCH päringu vastus kasutab sama formaat, mida POST päring:

<data register=”IVVc” sequence=”9729″ url=”/api/1/IVVc/10000014″ systemversion=”8.5.38.66″>

<IVVc>

<SerNr>10000014</SerNr>

…

<rows>

<row rownumber=”0″>

<stp>1</stp>

<ArtCode>10101</ArtCode>

<Quant>100</Quant>

<Price>25.00</Price>

<Sum>2375.00</Sum>

…

</row rownumber=”0″>

…

</rows>

…

</IVVc>

</data>

Antud päring muudab müügiarve, koodiga 10000014, maatriksi esimesel real artikli koguse 100 peale.

OAuth audentifitseerimise kohta loe täpsemalt SIIT

Registrite ja tabelite kirjeldused
Selleks, et leida enda vajaliku registri ja selle väljade tehnilised nimetused leiad Standard Books programmis:
moodul Tehnika > Aruanded > Eksport/import formaat.
Aruande seest on võimalik otsida kasutajale sobiv register ja selle sisesed väljade nimetused. Registrite ja tabelite kirjeldused leiad ka SIIT

REST API vers.2 DESCRIPTION IN ENGLISH

(SOAP, api url)