01.08.2018

OSC testaa: 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

Kohteen lisäykseen vaadittava formaatti on suhteellisen monimutkainen. Helpointa onkin tehdä ensin samantyyppinen kohde käyttöliittymän kautta ja hakea se sitten pohjaksi uudelle kohteelle.

Oletetaan, että järjestelmässä jo olevan kohteen id on 1.

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. Muokataan json-tiedostoa seuraavasti: poistetaan "object_id" (CA generoi sen automaattisesti) ja muutetaan kohteen nimeä (preferred_labels).

{
   "ok":true,
     "intrinsic_fields":{
       "object_id":"1", // poista tämä
       "lot_id":"1",
       "type_id":"27",
       "idno":"poljin",
       "is_deaccessioned":"0",
       "extent":"0",
       "access":"0",
       "status":"0",
       "deleted":"0",
      "rank":"1",
       "acl_inherit_from_ca_collections":"0",
       "acl_inherit_from_parent":"0",
       "access_inherit_from_parent":"0",
       "view_count":"0"
     },
     "preferred_labels":[
       {
         "locale":"en_US",
         "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