REST interfeisa koncepcija

Vispārējs apraksts

Horizon uzbūve

Visa Horizon funkcionalitāte tiek nodrošināta, izmantojot 2 pamata elementus:

sarakstus (arī atskaites) datu pieprasīšanai (tālāk saukta par entīšu kolekcijas klasi (angliski collection)).
ievadformas vienas rindiņas datu labošanai (tālāk saukta par entītes klasi (angliski entity)). Ievadformai var būt arī izveidotas apakšrindiņas, ja tādas ir nepieciešamas biznesa loģikai.

Piemēram, klientu saraksts Horizon (atbilstošā klase TDdmKlSar) izskatās šādi:

Viena klienta ieraksta labošanai pieejamā ievadforma (atbilstošā klase TDdmCustomer) izskatās šādi:

Horizon iespējams veikt uzskaiti par vairākām organizācijām. Sīkāk par vairāku uzņēmumu uzskaiti vienā Horizon datubāzē lasiet šeit: https://community.visma.com/t5/Zinasanu-baze-Integracija/Vairaku-uznemumu-uzskaite-viena-Horizon-datubaze/ta-p/645024

REST loģika

REST interfeisā katrai Horizon klasei ir izveidots savs pirmā līmeņa resurss atbilstoši klases vārdam. Zem katras klases resursa ir pieejami šai klasei specifiski apakšresursi.

REST interfeiss ir veidots pēc iespējas pašaprakstošs – vēršoties pie REST interfeisa, nonākam pie interfeisa ieejas punkta, kurā pārskaitīti visi pieejamie resursi. Tālāk, ejot uz katru no šiem resursiem, redzami nākamā līmeņa resursi, kas atkarībā no konteksta var būt apakšresursi vai operācijas ar izvēlēto resursu.

Katra resursa elementu skaidrojumu ir pieejams tam specifiskā WADL apakšresursā un izmantotās XML vai JSON datu struktūras skaidrojums ir pieejams kā XML Schema (XSD) apakšresurss.

Katram resuram ir redzams tā tips elementā <type> ar vērtībām collection un entity.

REST interfeiss darbojas, apmainoties ar XML vai JSON datu reprezentācijām. Sūtāmo datu formātu norāda galvenes (header) parametrā content-type, atbildes formātu var norādīt galvenes (header) parametrā Accept. Iespējamās vertības ir application/xml vai application/json. Ja pieprasījums galvenē nesatur Accept parametru, atbilde tiek formēta kā XML dokuments. Atsevišķiem resursiem iespējami arī citi formāti, piemēram, izdrukas var tikt sagatavotas application/pdf formātā.

Nosūtot datus obligāti jānorāda galvene Content-Type ar datu formāta veidu un kodējumu. Nosūtītie dati tiks apstrādāti norādītajā kodējumā, savukārt atbilde vienmēr būs UTF-8.

Content-Type: application/xml;charset=UTF-8

Pēc noklusējuma atbildē netiek iekļautas atstarpes (white space). Tas ļauj ievērojami samazināt pārsūtāmo datu apjomu. Ja atbildē nepieciešams saglabāt atstarpes un sadalījumu pa rindām, tad pieprasījumā var norādīt parametru prettyprint=true.

Kādus datus rādīt saistīto datu laukos nosaka foreignkey. Iespējamās vērtības - href, title, value vai to kombinācija. Noklusēti href.

Piemērs, ja norādīts foreignkey=href,title,value

<PK_KONTS>
	<href>/rest/TdmAccEd/497</href>
	<value>497</value>
	<title>1293 : Pārējo pamatlīdzekļu nolietojums</title>
</PK_KONTS>

Ieteicams izvairīties no noklusētās href vērtības izmantošanas. Tā vietā vienmēr, kad tas ir iespējams, ieteicams izmantot foreignkey=value. Tas saistīts ar to, ka href vērtības ģenerēšanai nepieciešamas papildus darbības un pie lielāka datu apjoma var tikt negatīvi iespaidota ātrdarbība.

/rest/TDdmCustomer/TDdmCustomer.xsd – resursa lauku un datu skaidrojošā XML shēma (XSD); Skaidro lauku vertību tipus un ierobežojumus. XSD apakšresursa vārds vienmēr sakrīt ar objekta klases vārdu kopā ar paplašinājumu "xsd".

Horizon mēdz būs lauki, kuriem ir iebūvētas vērtības un sistēma tās REST atgriež kodu veidā. Šādu lauku vērtības iespējams apskatīt XSD shēmā.

/rest/TDdmCustomer/TDdmCustomer.wadl – klases resursa, apakšresursu un iespējamo operāciju skaidrojums WADL (angliski Web Application Definition Language) formātā.

Vispārēji resursi

Klienta Horizon versija

Horizon un REST servera aktuālās versijas nsokaidrošanai

Resurss: rest/global/agentVersion