Rajapinta (API)

Rajapintojen mahdollisuuksia

API dokumentaatio

 Avoindata.fi -palvelu on rakennettu Drupal 8 ja CKAN:n pohjalle. Kaikki palvelussa olevat tiedot on saatavilla rajapinnan avulla. Tämä nettisivu kuvailee palvelun avoimen rajapinnan (RESTful API).

Käyttöoikeudet

Rajapinnan yli tehtävissä kutsuissa on samat käyttöoikeudet kuin web-käyttöliittymässä.

Esimerkiksi käyttäjän tulee olla organisaation jäsen, jos hän haluaa muokata sen aineistoja.

API kutsun tekeminen

Kutsun osoite:

https://www.avoindata.fi/data/api/3/action/group_list

Joka antaa seuraavanlaisen vastauksen:

{"help": "https://avoindata.fi/data/api/3/action/help_show?name=group_list",

"success": true,

"result": ["testi", "testi2fi"]}

Haku

Etsi: "Open street map"

URL: http://www.avoindata.fi/data/api/3/action/package_search?q=open+street+map

Vastaus:

{"count": 151, "results": ["ogc-web-map-tile-service", "signe-branderin-panoraamakuvat-1900-luvun-alun-helsingista", "vantaan-katujen-kunnossapidon-ajoneuvojen-telemetria-rajapinta", "espoon-liikennevaylien-keskilinjat", "helsingin-taidemuseon-prosenttirahahankkeet", "turun-kaupungin-kulttuurikohteita", "helsingin-katujen-puhdistussuunnitelmat", "helsingin-kaupungin-palauterajapinta", "espoon-opaskartta-vuodelta-1973", "espoon-opaskartta-vuodelta-1976"]}

API avaimen käyttö

Osaan rajapinnan toiminnoista vaaditaan API avain. API avain sisällytetään http-kutsun HEADER-osaan joko "Authorization" tai "X-CKAN-API-Key" merkinnällä varustettuna.

Esimerkiksi Python-koodissa näin:

request = urllib2.Request('http://avoindata.fi/data/api/3/action/dashboard_activity_list') request.add_header('Authorization', 'XXX') response_dict = json.loads(urllib2.urlopen(request, '{}').read())

API-avaimen saa, kun rekisteröityy palveluun käyttäjäksi. Oma API-avain (api key) löytyy omasta käyttäjäprofiilista. Ja ovat tyyliltään UUID-koodeja (esimerkiksi 123e4567-e89b-12d3-a456-426655440000).

Eli esimerkkiavaimella koodi menisi siis näin:

request = urllib2.Request('http://avoindata.fi/data/api/3/action/dashboard_activity_list') request.add_header('Authorization', '123e4567-e89b-12d3-a456-426655440000') response_dict = json.loads(urllib2.urlopen(request, '{}').read())

Uuden tietoaineiston lataaminen palveluun rajapinnan avulla

Tähän tarvitset API-avaimen.

URL: http://avoindata.fi/data/api/rest/dataset/osm

Vastaus:

{"id": "a3dd8f64-9078-4f04-845c-e3f047125028", "name": "osm", "title": "Open Street Map", ...

Tietoaineiston päivittäminen rajapinnan avulla

Tarvitset tähän API avaimen.

http --json POST http://avoindata.fi/data/api/3/action/resource_update id=<resource id> upload=@updated_file.csv Authorization:<api key>

Jos ei onnistu, niin API vastaa näin:

{ "success": false
"error":
    { "__type": "Not Found Error",
      "message": "Not found"
    },
"help": "...",
}

Tietoaineiston poistaminen rajapinnan avulla

Julkaistaan myöhemmin...

 

Lisädokumentaatio

Lisää dokumentaatiota löydät osoitteesta: https://docs.ckan.org/en/2.8/api/

Mika Honkanen, 25.1.2019