Application Programming Interface

Petities.nl can be approached through the Application Programming Interface (API) by third parties.

Eventually all data which is not privacy senstive can be read and to some extent written to the database.

When petitions are presented as the main feature of the application or the petities.nl brand is prominent, there should be no advertising in that same application. Advertisements are not an issue in an application or website which is mainly about something else (the subject of a certain petition for example) with petitions as an added bonus feature.

It is no problem to ask money for or in an application which connects to the API. Donations to petities.nl are always much appreciated and especially when users pay or donate because of a petitioning feature.

Below a design (in Dutch) with certain roles the API could and should serve. Currently not fully implemented. Contact webmaster@petities.nl if you intend to use the API.

Nr.	Gebruiker	Omgeving	GET	POST
1	petitionarissen	campagnewebsites en sociale netwerken	x	x
2	overheden	raadsinformatiesystemen, gemeentelijke website	x	x
3	applicatie-ontwikkelaars	mobiele telefoon operating systems, websites van derden	x
4	media	nieuws-websites	x
5	journalisten	subdomein of journalistenportal	x
6	Europetition	andere petitiewebsites	x	x
7	onderzoekers	statistische software	x

petitionarissen

Een petitionaris of diens ingehuurde ICT-er moet op een eigen campagnewebsite of op een sociaal netwerk informatie over een petitie kunnen laten zien en het ondertekenen makkelijk maken. Het actuele aantal ondertekeningen moet er zichtbaar worden (de bevestigde en de onbevestigde).

1. POST met name, e-mail, city, visibility
2. GET met (petition) id + name geeft naam van een petitie
3. GET met (petition) id + name_clean geeft het stuk uit de URL met underscores die uniek is voor een petitie voor oude petities uit de 2.0-site
4. GET met (petition) id + cached_slug geeft het stuk uit de URL met underscores die uniek is voor een petitie
5. GET met (petition) id + subdomain geeft het subdomein die handmatig is toegekend aan een petitie (if any)
6. GET met (petition) id + description geeft het korte stukje aanhef boven een petitie wat de petitionaris altijd mag veranderen
7. GET met (petition) id + initiator geeft de beschrijving van de petitionarissen in de aanhef van de petitie (bezorgde burgers, actiecomité, vrouwen of iets dergelijks)
8. GET met (petition) id + statement geeft het gedeelte van de petitie met de constatering van feiten
9. GET met (petition) id + request geeft het gedeelte van de petitie met de eis, de afsluiting van de petitie
10. GET met (petition) id + date_projected geeft de datum waarop de petitie waarschijnlijk overhandigd zal worden volgens de petitionaris (of overhandigd is als het om een petitie gaat voorbij fase ondertekenbaar
11. GET met (petition) id + organisation_id geeft terug aan welke organisatie de petitie is geadresseerd
12. GET met organisation_id geeft organisation_name terug; de naam van de organisatie zoals die aan het id is gekoppeld (bv. 658 is Tweede Kamer)
13. GET met (petition) id + petitioner_organisation geeft de beschrijving van de organisatie van de petitionaris 'comité, actiegroep dit of dat'
14. GET met (petition) id + petitioner name geeft de naam van de petitionaris, voornaam + achternaam
15. GET met (petition) id + maps_query geeft de postcode die hoort bij een petitie, voor zover door petitionaris opgegeven (vooral bij lokale petities).
16. GET met (petition) id + organisation_kind geeft wat voor organisatie organisation_id of organisation_name is
17. GET met (petition) id + signatures_count geeft aan hoeveel ondertekeningen een petitie heeft
18. GET met (petition) id + number_of_signatures_on_paper geeft aan hoeveel handtekeningen de petitionaris beweert op papier te hebben (nog niet geïmplementeerd)
19. GET met (petition) id + number_of_newsletters aantal voortgangsberichten er al zijn verstuurd over een petitie.
20. GET met (petition) id + created_at wanneer de petitie is aangemaakt via de petitie-wizard op de voorpagina
21. GET met (petition) id + last_confirmed_at wanneer de link om de petitie te bevestigen voor het laatst door de petitionaris is gevolg (het eigenlijke activeren van de petitie)

overheden

Overheden hebben eigen publiekssites waar informatie over petities ook getoond kan worden. Petities die de overheid in kwestie betreffen, aantallen ondertekeningen, nieuws erover, status en eventuele reacties van de politiek.

De lokettist van een overheid moet ook petities kunnen beheren en dat kan goed via een raadsinformatiesysteem. Dan kunnen er ook gelijk relevante raadsstukken en agenda gekoppeld worden aan een petitie. Dat systeem heeft dus ook een authenticatiesleutel nodig om te mogen schrijven in de database van petities.nl.

1. alles wat een petitionaris ook kan
2. POST (petition) id + status
3. POST newsitems
4. POST newsletters
5. POST

applicatie-ontwikkelaars

Dit is een categorie die van alles kan bedenken om eigen software te verrijken met functionaliteit of om mee te liften op de gratis content in de petities.nl database.

Bijvoorbeeld een 'klagen'-app op de mobiele telefoon waarmee je allerlei klantenservices, overheden, beheerders een bericht kan sturen zonder door vervelende formulieren hoeven te gaan. Die vult de app allemaal in. Een opzetje voor een petitie kan daar ook tussen zitten.

Of een lokatie-gebaseerde app die waarschuwt dat er in de buurt waar je wandelt een petitie is om te ondertekenen.

media

De media kunnen nieuws-websites opleuken met informatie over petities. Op grond van geografie of thema. Op de website van de lokale krant staat een overzichtje van petities en op thematische sites staat een overzicht naar petities met een bepaalde tag bijvoorbeeld.

journalisten

Een interface voor journalisten kan geauthentiseerd informatie over de petitionaris opvragen: naam, e-mail en telefoonnummer. Niet voordat een petitie in de fase ondertekenbaar is en niet nadat een petitie in de fase afgehandeld is gekomen. Spammers en willekeurige burgers kunnen de petitionaris dan niet bellen, maar mensen die zich wel uitvoerig als professionele journalist hebben geïdentificeerd (ooit) kunnen er wel inkomen. Bijvoorbeeld op basis van een lidnummer van de vereniging van journalisten of nog iets makkelijkers.

Europetition

Petities die op petities.nl beginnen moeten ook gedeeld kunnen worden met andere petitiesites in Europa. Europetition zorgt voor de vertaling. Petities op andere sites moeten ook zichtbaar zijn op petities.nl met naam, tekst en het totale aantal ondertekenaars elders. Ondertekeningen hier worden weer doorgegeven aan Europetition (maar niet de ondertekenaars, alleen het aantal).

onderzoekers

Zijn geïnteresseerd in trends en het verzamelen van data. Privacy van ondertekenaars moet wel beschermd blijven.

1. GET met (petition) id + updated_at de laatste bewerking van de petitionaris in de petitie, hoe actief een petitionaris is
2. GET met (petition) id + status geeft voor een bepaalde petitie de status weer, of een petitie al ondertekenbaar is bijvoorbeeld

• GET met status <concept,live,draft,rejected> geeft de lijst met petities weer voor een bepaalde status