Collective Access - rajapinta

Testaamme Collective Accessin rajapintaa

Collective Accessin rajapinta on käyttökelpoinen.

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ä?

Nykyaikainen REST-rajapinta on yksi tärkeimmistä kriteereistä melkeinpä mitä tahansa järjestelmää valittaessa. Erityisen tärkeää se on museotietojärjestelmän kohdalla.

Hyvä rajapinta 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.

Hyvät rajapinnat luovat myös turvaa käyttäjille käyttöliittymäsuunnittelijoiden hirmuvaltaa vastaan: Jos järjestelmän oma käyttöliittymä on kökkö, niin se voidaan korvata kokonaan tai osittain omalla käyttöliittymällä. Tästä hyvänä esimerkkinä on digiarkistomme JYX, jossa olemme kehittäneet omia työnkulkuja JYXin rajapintojen päälle.

Collective Accessin rajapinta

Collective Accessin rajapinta on käyttökelpoinen. Aineistosta saa tehtyä hakuja sekä fasettinäkymiä, ja aineiston muokkaaminen ja editoiminen onnistuu. Ainut esiin noussut rajoitus tiedoston lähettämisen puuttuminen. Tästä on tehty tiketti ja se luultavasti jossain vaiheessa toteutetaan.Toisaalta puute on suhteellisen helposti kierrettävissä oman toteutuksen kautta.

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ä.