Yleistä

Rajanpinnan avulla voit yhdistää taustajärjestelmäsi Adensyyn. Kaikki palveluumme kirjatut tiedot ovat käytettävissäsi rajapinnan kautta. Rajapintaa käytetään GET-kutsuilla. Kunkin kutsun yhteydessä välitetään parametreina autentikaatiota varten tunnukset, sekä xml-aineisto operaatiota varten.

Parametri	Kuvaus
apicode	Ympäristön apicode-tunnus, saadaan Adensylta.
Password	Apicodea vastaava salasana, saadaan Adensylta.
xmlquery	xml-aineisto operaatiota varten, tarkemmat kuvaukset alempana.

Ohjelmallisesti tehtävät rajapintakutsut tulee muistaa URL-enkoodata.

Sanasto ja keskeisimmät termit

Tietoluokka: Järjestelmässä oleva tietotyyppi, esimerkiksi company tai contactperson. Vastaa tietokannan taulua.
Attribuutti: Tietoluokalla oleva tieto, esimerkiksi contactperson-tietoluokan firstname-attribuutti sisältää kyseisen henkilön etunimen. Vastaa tietokannan taulun saraketta.
Ei tule sekoittaa xml-elementtien attribuuttien kanssa. Selvyyden vuoksi tietoluokkien attribuutteihin viitataan dokumentissa termillä “Tietoluokka-attribuutti”.

Testaus

Testaukseen voi käyttää demo-ympäristöä. Operaatiokuvauksen lopussa olevat kokonaiset esimerkkikutsut ovat toimivia ja niitä voi kokeilla esimerkiksi selaimella.

---

Haku

URL: http://app.adensy.com:8080/AESWebApp/api/episteme/production/get

xmlquery: <dataclass name="contactperson" limit=”50”> <condition> <field>firstname</field> <operator>equal</operator> <parameter>Jaska</parameter> </condition> </dataclass> Haku voi sisältää vain yhden dataclass-elementin. Condition-elementtejä voi olla useampi. Conditionin field-kenttä määrää tarkasteltavan tietoluokka-attribuutin, operator määrää tarkasteluoperaattorin ja parameter-kenttä verrattavan arvon. Operator-kentälle voi antaa seuraavia arvoja:

Operaattori	Kuvaus
equal	Palauttaa rivit, joilla fieldin arvo on sama kuin parameter-kentän arvo
notequal	Palauttaa rivit, joilla fieldin arvo on eri kuin parameter-kentän arvo
less	Palauttaa rivit, joilla fieldin arvo on vähemmän kuin parameter-kentän arvo. Toimii ainoastaan fieldeillä, joita voidaan asettaa suuruusjärjestykseen SQL:ssä.
greater	Palauttaa rivit, joilla fieldin arvo on enemmän kuin parameter-kentän arvo. Toimii ainoastaan fieldeillä, joita voidaan asettaa suuruusjärjestykseen SQL:ssä.

Operaattoreina voi myös käyttää natiivi SQL-operaattoreita, kun halutaan vertailla fieldiä, joka ei ole tietoluokka-attribuutti (esim. haku rowid perusteella).

<dataclass name="contactperson" limit=”50”> <condition> <field>rowid</field> <operator>=</operator> <parameter>13</parameter> </condition> </dataclass> Kun tietoluokka-attribuutti viittaa johonkin tietoluokkaan (kuten contactpersonin tietoluokka-attribuutti “company”), haku tehdään attribuutin titlen perusteella. Haku voidaan myös suorittaa rowid mukaan käyttämällä useLinkId-attribuuttia field-elementissä: <dataclass name="contactperson" limit=”50”> <condition> <field useLinkId=”true”>company</field> <operator>equal</operator> <parameter>13</parameter> </condition> </dataclass> Paluuaineisto: <contactperson rowid="4653" titlevalue="Seppo Hakonen"> <firstname>Jaska</firstname> <lastname>Jokunen</lastname>
<company rowid="2961">ABB Oy</company> <jobtitle/> <mobilephone>050 33 24 321</mobilephone> <phonenumber/> <email>jaska.jokunen@fi.abb.com </email> <fax/> <streetaddress/>
<postalcode/>
<city/>
<owner rowid="46">Kalevi Sinisalmi</owner> <picture>0</picture> <twitterusername/> <mailchimpemail/> <description/> <externalDSpersonid/> </contactperson>
<contactperson rowid="4654" titlevalue="Maijastiina Salmivaara"> <firstname>Jaana</firstname> <lastname>Jokunen</lastname>
<company rowid="2962">Abcell</company> <jobtitle>Executive Administrator</jobtitle> <mobilephone>050 443 0795 </mobilephone> <phonenumber/>
<email>abcell@kolumbus.fi </email>
<fax/>
<streetaddress/>
<postalcode/>
<city/>
<owner rowid="46">Kalevi Sinisalmi</owner> <picture>0</picture>
<twitterusername/>
<mailchimpemail/>
<description/>
<externalDSpersonid/> </contactperson> </return>

Paluuaineisto sisältää haetut rivit. Tietoluokka-attribuuteilla, jotka viittaavat toiseen tietoluokkaan, on lisäksi rowid-attribuutti, joka kertoo viitatun rivin rowid:n. Kokonainen esimerkkikutsu:

http://app.adensy.com:8080/AESWebApp/api/episteme/production/get?apicode=adensy&password=api2015&xmlquery=<dataclass name="contactperson"><condition><field useLinkId="true">company</field><operator>equal</operator><parameter>48</parameter></condition></dataclass>

---

Rivin lisäys

URL: http://app.adensy.com:8080/AESWebApp/api/episteme/production/add

xmlquery:

<xmldata>
<dataclass name="contactperson" > <firstname>Jaska</firstname> <lastname>Jokunen</lastname>
<person field=”externalid”>512</person> </dataclass> </xmldata>

Dataclass-elementtejä voi olla useampi, jolloin voidaan lisätä monta riviä kerralla. Dataclass-elementin name -attribuutti sisältää tietoluokan nimen (esim. company, contactperson). Dataclassin alla on lisättävän rivin arvot, elementin nimeksi tulee tietoluokka-attribuutin nimi (esim firstname, lastname) ja arvoksi haluttu arvo. Tietoluokka-attribuutit, joille ei anneta arvoa, jäävät tyhjäksi. Kun tietoluokka-attribuutti viittaa johonkin toiseen tietoluokkaan (kuten contactpersonin tietoluokka- attribuutti “company”), on arvoksi annettava halutun rivin rowid. Listaukset tietoluokista ja tietoluokka-attribuuttien nimistä löytyvät erillisestä dokumentista.

Paluuaineisto: <?xml version="1.0" encoding="UTF-8"?> <return> <result index="0" success="true">5353</result> </return>

Index-attribuutti viittaa aikaisempiin dataclass-elementtien indeksiin. Success-attribuutti sisältää tiedon, onko lisäys onnistunut. Elementin arvona oleva numero on rivin rowid järjestelmässä. Kokonainen esimerkkikutsu: http://app.adensy.com:8080/AESWebApp/api/episteme/production/add?apicode=adensy&password=api2015&xmlquery=JaskaJokunen

---

Päivitys

URL: http://app.adensy.com:8080/AESWebApp/api/episteme/production/update xmlquery: <xmldata>
<dataclass name="contactperson" rowid=”5353”> <firstname>Jaska</firstname> <lastname>Jokunen</lastname> <owner>1332</owner> </dataclass> </xmldata> Päivityksessä on samanlaiset käytännöt kuin lisäys-operaatiossa. Useamman rivin päivitys onnistuu käyttämällä montaa dataclass-elementtiä. Päivityksessä tarvitaan myös kullekin dataclass-elementille attribuutti “rowid”, jolla määritetään päivitettävä rivi. Linkityskenttien tapauksessa annetaan arvoksi linkitettävän kentän rowid-tunniste. Paluuaineisto: <?xml version="1.0" encoding="UTF-8"?> <return> <result index="0" success="true">5353</result> </return> Index-attribuutti viittaa aikaisempiin dataclass-elementtien indeksiin. Success-attribuutti sisältää tiedon, onko päivitys onnistunut. Elementin arvona oleva numero on rivin rowid järjestelmässä. Kokonainen esimerkkikutsu: http://app.adensy.com:8080/AESWebApp/api/episteme/production/add?apicode=adensy&password=api2015&xmlquery=<xmldata><dataclass name="contactperson"><firstname>Jaska</firstname><lastname>Jokunen</lastname></dataclass></xmldata>

---

Poisto

URL: http://app.adensy.com:8080/AESWebApp/api/episteme/production/delete xmlquery: <dataclass name="contactperson"> <rowid>2961</rowid> </dataclass> Poisto-operaatiossa annetaan vain poistettavan rivin rowid. Usean rivin poisto ei ole mahdollista yhdellä kutsulla. Paluuaineisto: <?xml version="1.0" encoding="UTF-8"?> <return> <result success="true"/> </return> Paluuaineisto kertoo, onnistuiko poisto. Kokonainen esimerkkikutsu: http://app.adensy.com:8080/AESWebApp/api/episteme/production/delete?apicode=adensy&password=api2015&xmlquery=<dataclass name=”contactperson”><rowid>2961</rowid></dataclass>