19.10.2018

Collective Access - rajapinta

Testaamme Collective Accessin rajapintaa

Päivän testailun jälkeen Collective Accessin rajapinta vaikuttaa hyvältä.

Ensimmäinen testattava asia uuden verkkopalvelun (Collctive Accessin tässä tapauksessa) kokeilussa on sen REST-rajapinnan käyttökelpoisuuden selvittäminen. Vaikka koneille tarkoitetut rajapinnat eivät peruskäyttäjää juurikaan ilahduta, ovat ne kehittäjän/ylläpitäjän näkökulmasta niin tärkeitä, että niistä pitää blogissakin kertoa.

ca_browse.png

Miksi rajapinta on tärkeä?

Hyvä rajapinta vapauttaa käyttöliittymän ikeestä ja helpottaa suuresti aineiston tuomista/viemistä/muokkaamista ja kaikkea sitä puljaamista, mitä aineistolle joudutaan tekemään. Ehkä halutaan luoda hyvin yksinkertainen lomake juuri tietynlaisen aineiston syöttöön. Tai ehkä meille tulee jatkuvasti aineistoa, joka pitää viedä mahdollisimman vähällä vaivalla suoraan kokoelmanhallintaan. Tai aineistosta halutaan reaalikaista analyysiä, jota järjestelmän omat raportointityökalut eivät osaa tehdä. Nämä kaikki voidaan toteuttaa rajapinnan kautta.

Collective Accessin rajapinta

Päivän testailun jälkeen Collective Accessin rajapinta vaikuttaa hyvältä. Aineistosta saa tehtyä hakuja sekä fasettinäkymiä, ja aineiston muokkaaminen ja editoiminen onnistuu. Seuraavassa on esimerkkejä rajapintakutsuista curl -ohjelmiston avulla.

Kirjautuminen

Monet rajapinnan toiminnot vaativat kirjautumisen. Se tehdään seuraavasti:

curl http://administrator:changeme@localhost/providence/service.php/auth/login

Kutsu palauttaa tokenin, jonka avulla seuraavat kutsut voidaan autentikoida.

Haut

Kokotekstihaku toimii siten, että kerrotaan mistä perustyypistä halutaan hakea ja sitten hakusana (ei vaadi autentikointia):

http://localhost/providence/service.php/find/ca_objects?q=poljin&pretty=1

Jos haluaa hakea vain tietystä kentästä, niin se tapahtuu seuraavasti:

http://localhost/providence/service.php/find/ca_objects?q=ca_object_labels.name:polkup*&pretty=1

Fasettihaut onnistuvat myös ja ne on dokumentoitu täällä.

Uuden kohteen lisäys

Alla on yksinkertaisin mahdollinen uusi objekti, jolla on pelkästään id ja nimi:

{
     "intrinsic_fields":{
       "type_id":"26", // pakollinen, kertoo mitä tyyppiä kohde on
       "idno":"poljin"
     },
     "preferred_labels":[
       {
         "locale":"fi_FI",
         "name":"polkupyörän poljin"  // uuden kohteen nimi
      }
   ]
}

Nyt voidaan luoda uusi kohde seuraavasti:

curl -XPUT http://localhost/providence/service.php/item/ca_objects?authToken=sinun_tokenisi_tähän -d @new.json

Monesti on kuitenkin tarvet tehdä monimutkaisempia kohteita. Käytännössä helpointa onkin tehdä ensin samantyyppinen kohde käyttöliittymän kautta ja hakea se sitten pohjaksi uudelle kohteelle.

curl -XGET 'http://localhost/providence/service.php/item/ca_objects/id/1?pretty=1&format=edit&authToken=sinun_tokenisi_tähän' > new.json

 Tämä tallettaa kohteen tiedot tiedostoon new.json. Tätä voidaan käyttää uusien tietueiden luomisen pohjana (muista poistaa "object_id") tai tietojen muokkaamiseen. 

Kohteen muokkaaminen

Muutetaan seuraavaksi kohteen nimeä. Tee edit.json -niminen tiedosto ja kopioi alla olevan siihen. 

​{
    "remove_all_labels": true,
    "preferred_labels":[
         {
            "locale":"fi_FI",
            "name":"Ihan eri nimi"
        }
    ]
}

Huomaa "remove_all_labels" -attribuutti. Tämä poistaa alta kaikki entiset nimet. Jos tätä ei ole, niin uusi nimi vain lisätään muiden jatkoksi.

Muutos toteutetaan kutsumalla REST-rajapintaa seuraavasti  (editoidaan objektia, jonka id on 1):

curl -XPUT 'http://localhost/providence/service.php/item/ca_objects/id/1?authToken=oma_tokenisi_tähän' -d @edit.json 

Tarkempaa dokumentointia editoinnista löydät tästä.