API

Rahvaalgatusel on avalik API, mida saab kasutada nii serveri kui ka brauseri kaudu. Nii saab soovi korral kuvada algatusi ja kogutud allkirjade arvu ka väljaspool Rahvaalgatust. Nõnda kasutab seda näiteks Karusloomafarmide keelustamise kampaania oma lehel.

Kogu API dokumentatsioon on loetav SwaggerHubis ja masinloetavalt OpenAPI v3 formaadis openapi.yaml failis.

Kombineerides erinevaid API päringuid saad enda lehel kuvada näiteks koondvaate Rahvaalgatuses toimuvast:

Mis ettepanekuid rahvas Riigikogule saadab?

Arutelu käib idee üle ja toetust koguvad algatust.

7 päeva jooksul enim toetust kogunud algatused

Uus info

Eelnev näide kasutab Rahvaalgatuse statistika, algatuste ja menetlusinfo API-sid. All leiad kõigi kolme kohta näiteid, viited dokumentatsioonile ning koodijuppe kasutuseks.

Algatuste statistika

Kui soovid veebilehele lisada kõikide algatuste koondarvu, saad selle info https://rahvaalgatus.ee/statistics aadressilt.

Mis ettepanekuid rahvas Riigikogule saadab?

Arutelu käib idee üle ja toetust koguvad algatust.

Statistikapäringuga saad teada aktiivsete algatuste (need, mis pole tähtaega ületanud) arvu faaside lõikes ning allkirjade summa. Ülemise näite saad teha selliselt:

Arutelu käib <strong id="edit-count">…</strong> idee üle ja
toetust koguvad <strong id="sign-count">…</strong> algatust.
fetch("https://rahvaalgatus.ee/statistics", {
  headers: {Accept: "application/vnd.rahvaalgatus.statistics+json; v=1"}
}).then(function(res) { return res.json() }).then(function(stats) {
  document.getElementById("edit-count").textContent =
    stats.activeInitiativeCountsByPhase.edit
  document.getElementById("sign-count").textContent =
    stats.activeInitiativeCountsByPhase.sign
})

Oluline on teha päring Accept: application/vnd.rahvaalgatus.statistics+json; v=1 päisega. Ilma selleta ei tea server, et soovid teha API päringu, ja tagastab sulle hoopis HTMLi. v=1 aga määrab API versiooni. See garanteerib, et API muudatuste puhul jääb su leht õigesti tööle.

Kui tahaksid ligipääsu statistikale, mida me hetkel ei väljasta, palun anna meile sellest GitHubi kaudu teada.

Algatuste loetelu

Kui soovid veebilehele loetelu Rahvaalgatuses kajastuvatest algatustest, saad selle info https://rahvaalgatus.ee/initiatives päringuga. Näiteks võid oma lehe küljeribal välja tuua viis aktiivset ja kõige rohkem allkirju kogunud algatust:

5 populaarseimat rahvaalgatust

Alustuseks piisab ühest loetelu (<ol>) elemendist.

<ol id="initiatives"></ol>

Algatusi pärides saad ka määrata, kuidas neid järjestada, filtreerida algatuse faasi järgi ning piirata tagastatud algatuste arvu. Määrame, et soovime ainult allkirjastamises olevaid algatusi (phase=sign), sorteerida nad allkirjade järgi kasvavas järjekorras (order=-signatureCount) ja ainult esimest viite (limit=5):

var URL = "https://rahvaalgatus.ee"

fetch(URL + "/initiatives?phase=sign&order=-signatureCount&limit=5", {
  headers: {Accept: "application/vnd.rahvaalgatus.initiative+json; v=1"}
}).then(function(res) { return res.json() }).then(function(body) {
  var ol = document.getElementById("initiatives")

  initiatives.forEach(function(initiative, i) {
    var li = document.createElement("li")

    var a = document.createElement("a")
    a.href = URL + "/initiatives/" + initiative.id
    a.textContent = initiative.title
    li.appendChild(a)

    var count = initiative.signatureCount
    li.appendChild(document.createTextNode(" (" + count + " allkirja)"))
    ol.appendChild(li)
  })
})

Kui soovid filtreerida algatusi allkirjastamisaktiivsuse järgi, lisa juurde signedSince parameeter kuupäevaga. See lisab vastusele juurde ka signaturesSinceCount välja, kust leiad antud ajavahemikul tehtud allkirjade arvu. Ülal näites nähtud "viimase 7 päeva algatuste" loendi saad luua järgmiselt:

<ol id="initiatives"></ol>
var URL = "https://rahvaalgatus.ee"

var since = new Date
since.setDate(since.getDate() - 6)

var url = URL + "/initiatives"
url += "?signedSince=" + since.toISOString().slice(0, 10)
url += "&order=-signaturesSinceCount"
url += "&limit=3"
fetch(url, {
  headers: {Accept: "application/vnd.rahvaalgatus.initiative+json; v=1"}
}).then(function(res) { return res.json() }).then(function(initiatives) {
  var ol = document.getElementById("initiatives")

  initiatives.forEach(function(initiative, i) {
    var li = document.createElement("li")

    var a = document.createElement("a")
    a.href = URL + "/initiatives/" + initiative.id
    a.textContent = initiative.title
    li.appendChild(a)

    var added = initiative.signaturesSinceCount
    var total = initiative.signatureCount
    var t = " +" + added + " allkirja (" + total + " kokku)"
    li.appendChild(document.createTextNode(t))
    ol.appendChild(li)
  })
})

Oluline on teha päring Accept: application/vnd.rahvaalgatus.initiative+json; v=1 päisega. Ilma selleta ei tea server, et soovid teha API päringu, ja tagastab sulle hoopis HTMLi. v=1 aga määrab API versiooni. See garanteerib, et API muudatuste puhul jääb su leht õigesti tööle.

Kui tahaksid ligipääsu infole, mida me hetkel APIs ei väljasta, palun anna meile sellest GitHubi kaudu teada.

Algatuse allkirjade arv

Ehk soovid oma algatuse reklaamlehel kuvada loendurit, mitu allkirja oled juba kogunud:

Algatus "Lendorava ja metsade kaitseks" on kogunud…

Allkirja

Oma algatuse allkirjade arvu saad pärida https://rahvaalgatus.ee/initiatives/{initiativeUuid} aadressilt.

Algatuse id d400bf12-f212-4df0-88a5-174a113c443a puhul näeks loenduri HTML ja JavaScript välja umbes selliselt:

Algatus "Lendorava ja metsade kaitseks" on kogunud <span id="count"></span> allkirja.
var URL = "https://rahvaalgatus.ee"

fetch(URL + "/initiatives/d400bf12-f212-4df0-88a5-174a113c443a", {
  headers: {Accept: "application/vnd.rahvaalgatus.initiative+json; v=1"}
}).then(function(res) { return res.json() }).then(function(body) {
  document.getElementById("count").textContent = body.signatureCount
})

Oluline on teha päring Accept: application/vnd.rahvaalgatus.initiative+json; v=1 päisega. Ilma selleta ei tea server, et soovid teha API päringu, ja tagastab sulle hoopis HTMLi. v=1 aga määrab API versiooni. See garanteerib, et API muudatuste puhul jääb su leht õigesti tööle.

Kui tahaksid ligipääsu infole, mida me hetkel APIs ei väljasta, palun anna meile sellest GitHubi kaudu teada.

Algatuste menetlusinfo

Igal algatusega on seotud ka menetlusinfot, kus kajastuvad sündmused allkirjastamisest ning käekäigust Riigikogus ja valitsusasutustes. Menetlusinfot saab pärida kõikide algatuste kohta https://rahvaalgatus.ee/initiative-events aadressilt.

Viie viimati uuendatud menetlusinfoga algatuse kuvamine võib välja näha selliselt:

Värske menetlusinfoga algatused

Kõigepealt teeme päringu https://rahvaalgatus.ee/initiative-events aadressile, küsides algatuste sündmusi toimumise järjekorras (order=-occurredAt). Piirdume viie tagastatud sündmusega (limit=5) ja selleks, et kuvada menetlusinfo pealkirja kõrval ka algatuse pealkirja, palume lisada ka algatuse info (include=initiative). Et mitte kuvada sama algatust nimekirjas kaks korda, lisame ka distinct=initiativeId, mis eemaldab duplikaadid peale sorteerimist.

<ol id="initiative-events"></ol>
var URL = "https://rahvaalgatus.ee"

var path = "/initiative-events"
path += "?include=initiative"
path += "&distinct=initiativeId"
path += "&order=-occurredAt"
path += "&limit=5"
fetch(URL + path, {
  headers: {
    Accept: "application/vnd.rahvaalgatus.initiative-event+json; v=1"
  }
}).then(getJson).then(function(events) {
  var ol = document.getElementById("initiative-events")

  events.forEach(function(event, i) {
    var li = document.createElement("li")

    var a = document.createElement("a")
    a.href = URL + "/initiatives/" + event.initiativeId + "/events/" + event.id
    a.textContent = event.initiative.title
    li.appendChild(a)
    li.appendChild(document.createTextNode(": " + event.title))

    ol.appendChild(li)
  })
})

Oluline on teha päring Accept: application/vnd.rahvaalgatus.initiative-event+json; v=1 päisega. Ilma selleta ei tea server, et soovid teha API päringu, ja tagastab sulle hoopis HTMLi. v=1 aga määrab API versiooni. See garanteerib, et API muudatuste puhul jääb su leht õigesti tööle.

Kui tahaksid ligipääsu infole, mida me hetkel APIs ei väljasta, palun anna meile sellest GitHubi kaudu teada.