Application Programming Interface: verschil tussen versies

Uit Petities
Ga naar: navigatie, zoeken
(opzetje voor een license)
k (→‎application developers)
 
(25 tussenliggende versies door dezelfde gebruiker niet weergegeven)
Regel 3: Regel 3:
 
Eventually all data which is not privacy senstive can be read and to some extent written to the database.  
 
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. 
+
Below a design (in Dutch) with certain roles the API could and should serve. Currently (March 2018) not fully implemented. Contact webmaster@petities.nl if you intend to use the API and would like a key.
−
 
+
−
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.  
+
  
  
Regel 13: Regel 9:
 
|-
 
|-
 
!width=3% |Nr.
 
!width=3% |Nr.
−
!width=30%|Gebruiker
+
!width=20%|User
−
!width=31%|Omgeving
+
!width=20%|Environment
 +
!width=31%|Example
 
!width=3% |GET  
 
!width=3% |GET  
 
!width=3% |POST
 
!width=3% |POST
Regel 20: Regel 17:
 
|-
 
|-
 
|1  
 
|1  
−
|petitionarissen
+
|petitioners
−
|campagnewebsites en sociale netwerken
+
|campaign websites, social networks
 +
|plasticsoup.org
 
|x
 
|x
 
|x
 
|x
Regel 27: Regel 25:
 
|-
 
|-
 
|2
 
|2
−
|overheden
+
|governments
−
|raadsinformatiesystemen, gemeentelijke website
+
|raadsinformatiesystemen, government website
 +
|SIM groep, MSI, Notubiz, Gemeenteoplossingen, CompanyWebcast?
 
|x
 
|x
 
|x
 
|x
Regel 34: Regel 33:
 
|-
 
|-
 
|3
 
|3
−
|applicatie-ontwikkelaars
+
|application developers
−
|mobiele telefoon operating systems, websites van derden
+
|mobile apps, third party sites
 +
|[https://tippiq.nl Tippiq]
 
|x
 
|x
 
|
 
|
Regel 42: Regel 42:
 
|4
 
|4
 
|media
 
|media
−
|nieuws-websites
+
|news websites
 +
|ANP
 
|x
 
|x
 
|
 
|
Regel 48: Regel 49:
 
|-
 
|-
 
|5
 
|5
−
|journalisten
+
|journalists
−
|subdomein of journalistenportal
+
|investigative news reports
 +
|[http://sargasso.nl Sargasso], [http://www.vvoj.nl/ VVOJ]
 
|x
 
|x
 
|
 
|
Regel 55: Regel 57:
 
|-
 
|-
 
|6
 
|6
−
|Europetition
+
|European partners
−
|andere petitiewebsites
+
|connected Europe wide petitions, European Citizens' Initiatives
 +
|[http://openpetition.de OpenPetition], [http://petitie.be Petitie.be]
 
|x
 
|x
 
|x
 
|x
Regel 62: Regel 65:
 
|-
 
|-
 
|7
 
|7
−
|onderzoekers
+
|researchers
−
|statistische software
+
|statistische software, issue mapping
 +
|Rathenau Instituut, Universiteit Twente, Universiteit Tilburg, [http://www.howaboutyou.nl/issuemanagement/ HowAboutYou]
 
|x
 
|x
 
|
 
|
 
|}
 
|}
  
 +
The base URI for an API call is to be announced, but the call itself (for API version 1) will start with /api/v1/ followed by the actual POST or GET command. The commands in the table below are referring to the database queries for which the precise API call is not yet known.
  
−
==petitionarissen==
+
==petitioners==
  
−
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).
+
These use cases are to be made possible for a petitioner/campaigner:
  
−
# POST met name, e-mail, city, visibility
+
* show a widget on a third party campaign website where the petition can be signed (BASIC FEATURE)
−
# GET met (petition) id + name geeft naam van een petitie
+
* show a counter with the number of signatures for the petition so far (BASIC FEATURE)
−
# 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
+
* inject the name, city and e-mailaddress as a signature by following a customised, personalised link from an e-mail newsletter (BASIC FEATURE)
−
# GET met (petition) id + cached_slug geeft het stuk uit de URL met underscores die uniek is voor een petitie
+
* embed a selection of petitions to promote/discuss on your personal blog (NICE FEATURE, variation on 1st)
−
# GET met (petition) id + subdomain geeft het subdomein die handmatig is toegekend aan een petitie (if any)
+
* create a graphic with signatures per hour or per day within a chosen time frame, e.g. 'the past days', 'when we came on tv', 'the days after the launch', 'in the different seasons last year', 'around lunch time on weekdays'(NICE TO HAVE, variation on 2nd)
−
# GET met (petition) id + description geeft het korte stukje aanhef boven een petitie wat de petitionaris altijd mag veranderen
+
* (bonus: show an up-to-date timeline with date of start, hand over of and expected answer to the petition) (BONUS, date of start not recorded)
−
# GET met (petition) id + initiator geeft de beschrijving van de petitionarissen in de aanhef van de petitie (bezorgde burgers, actiecomité, vrouwen of iets dergelijks)
+
−
# GET met (petition) id + statement geeft het gedeelte van de petitie met de constatering van feiten
+
−
# GET met (petition) id + request geeft het gedeelte van de petitie met de eis, de afsluiting van de petitie
+
−
# 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]]
+
−
# GET met (petition) id + organisation_id geeft terug aan welke organisatie de petitie is geadresseerd
+
−
# 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)
+
−
# GET met (petition) id + petitioner_organisation geeft de beschrijving van de organisatie van de petitionaris 'comité, actiegroep dit of dat'
+
−
# GET met (petition) id + petitioner name geeft de naam van de petitionaris, voornaam + achternaam
+
−
# GET met (petition) id + maps_query geeft de postcode die hoort bij een petitie, voor zover door petitionaris opgegeven (vooral bij lokale petities).
+
−
# GET met (petition) id + organisation_kind geeft wat voor organisatie organisation_id of organisation_name is
+
−
# GET met (petition) id + signatures_count geeft aan hoeveel ondertekeningen een petitie heeft
+
−
# GET met (petition) id + number_of_signatures_on_paper geeft aan hoeveel handtekeningen de petitionaris beweert op papier te hebben (nog niet geïmplementeerd)
+
−
# GET met (petition) id + number_of_newsletters aantal voortgangsberichten er al zijn verstuurd over een petitie.
+
−
# GET met (petition) id + created_at wanneer de petitie is aangemaakt via de petitie-wizard op de voorpagina
+
−
# 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==
+
{|class=wikitable
 +
|-
 +
!width=5% |number
 +
!width=5% |condition
 +
!width=45%|command
 +
!width=50%|description
  
−
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.  
+
|-
 +
|1
 +
|petitions.id, petitions.status=live
 +
|POST petitions.id, new_signatures.person_name, new_signatures.person_email, new_signatures.person_city, new_signatures.visibility
 +
| ''a signature''
  
−
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.
+
|-
 +
|2
 +
|NOT NULL
 +
| GET petitions.id, petition_translations.name, locale=nl
 +
| ''name of a petition, can change''
  
−
# alles wat een petitionaris ook kan
+
|-
−
# POST (petition) id + status
+
|3
−
# POST newsitems
+
|NOT NULL
−
# POST newsletters
+
| GET petitions.id, petitions.slug
−
# POST
+
| ''the part of the URL with dashes, unique for a petition (can change)''
  
−
==applicatie-ontwikkelaars==
+
|-
 +
|4
 +
|NOT NULL
 +
| GET petitions.id, petitions.subdomain
 +
| ''fixed unique subdomain added during moderation''
 +
 
 +
|-
 +
|5
 +
|NOT NULL
 +
| GET petitions.id, petition_translations.description, locale=nl
 +
| ''short introtext above a petition (can change)''
 +
 
 +
|-
 +
|6
 +
|NOT NULL
 +
| GET petitions.id, petition_translations.initiators, locale=nl
 +
| ''fixed description of signatories, 1st part of the petition''
 +
 
 +
|-
 +
|7
 +
|NOT NULL
 +
| GET petitions.id, petition_translations.statement, locale=nl
 +
| ''fixed observation of facts in 2nd part of petition''
 +
 
 +
|-
 +
|8
 +
|NOT NULL
 +
| GET petitions.id, petition_translations.request, locale=nl
 +
| ''fixed demand of the petition, 3rd and last part of the petition''
 +
 
 +
|-
 +
|9
 +
|NOT NULL
 +
| GET petitions.id, petitions.date_projected
 +
| ''date of hand over, changes more often as hand over approaches, also an expiration date of the petition''
 +
 
 +
|-
 +
|10
 +
|NOT NULL
 +
| GET petitions.id, organisation_id
 +
| ''recipient of petition, for example local counsil or parliament''
 +
 
 +
|-
 +
|11
 +
|
 +
| GET organisations.id, organisation_name
 +
| ''name of the organisation (for example bv. id=658 is parliament)''
 +
 
 +
|-
 +
|12
 +
|
 +
| GET organisations.id, organisation_kind
 +
|  ''district, water_county, counsil, plusregion, government, parliament, european_union, collective''
 +
 
 +
|-
 +
|13
 +
|NOT NULL
 +
| GET petitions.id, petitioner_organisation
 +
| ''organisation of the petitioner, optional.''
 +
 
 +
|-
 +
|14
 +
|NOT NULL
 +
| GET petitions.id, maps_query area
 +
| ''where the petition is situated, if applicable''
 +
 
 +
|-
 +
|15
 +
|NOT NULL
 +
| GET petitions.id, signatures_count
 +
| ''how many signatures''
 +
 
 +
|-
 +
|16
 +
|NOT NULL
 +
| GET petitions.id, number_of_signatures_on_paper
 +
|''how many signatures the petitioner claims to have collected through other means (on paper)''
 +
 
 +
|-
 +
|17
 +
|NOT NULL
 +
| GET petitions.id, answer_due_date
 +
|''when an answer can be expected after the handover, receiving organisation will change it often''
 +
|}
 +
 
 +
==governments==
 +
 
 +
In addition to the use cases for the petitioner, these are to be made possible for local governments
 +
 
 +
* show petitions in an app or website specific for some locality/recipient (BASIC FEATURE)
 +
* change the status of a petition (BASIC FEATURE)
 +
* add a formal case number for a petition upon reception (BASIC FEATURE)
 +
* embed petitions for the citizenry of a locality on a website
 +
* link existing formal documents as related to the petition
 +
* show citizen engagement with statistics (number of signatures, subscriptions to updates)
 +
* show deadlines for petitions (hand over, answer, public hearing, committee meetings, etc.)
 +
* post news updates connected to petitions
 +
 
 +
{|class=wikitable
 +
|-
 +
!width=5% |number
 +
!width=5% |condition
 +
!width=45%|command
 +
!width=50%|description
 +
 
 +
|-
 +
|2
 +
|organisation.id in API key
 +
| GET petitions.id, petition_translations.name, locale=nl
 +
| ''name of a petition, can change''
 +
 
 +
|-
 +
|6
 +
|organisation.id in API key
 +
| GET petitions.id, petition_translations.initiators, locale=nl
 +
| ''fixed description of signatories, 1st part of the petition''
 +
 
 +
|-
 +
|7
 +
|organisation.id in API key
 +
| GET petitions.id, petition_translations.statement, locale=nl
 +
| ''fixed observation of facts in 2nd part of petition''
 +
 
 +
|-
 +
|8
 +
|organisation.id in API key
 +
| GET petitions.id, petition_translations.request, locale=nl
 +
| ''fixed demand of the petition, 3rd and last part of the petition''
 +
 
 +
|-
 +
|9
 +
|organisation.id in API key
 +
| GET petitions.id, petitions.date_projected
 +
| ''date of hand over, changes more often as hand over approaches, also an expiration date of the petition''
 +
 
 +
|-
 +
|10
 +
|organisation.id in API key
 +
| GET petitions.id, organisation_id
 +
| ''recipient of petition, for example local counsil or parliament''
 +
 
 +
|-
 +
|13
 +
|organisation.id in API key
 +
| GET petitions.id, petitioner_organisation
 +
| ''organisation of the petitioner, optional.''
 +
 
 +
|-
 +
|14
 +
|organisation.id in API key
 +
| GET petitions.id, maps_query area
 +
| ''where the petition is situated, if applicable''
 +
 
 +
|-
 +
|15
 +
|organisation.id in API key
 +
| GET petitions.id, signatures_count
 +
| ''how many signatures''
 +
 
 +
|-
 +
|16
 +
|organisation.id in API key
 +
| GET petitions.id, number_of_signatures_on_paper
 +
|''how many signatures the petitioner claims to have collected through other means (on paper)''
 +
 
 +
|-
 +
|17
 +
|organisation.id in API key
 +
| GET petitions.id, answer_due_date
 +
|''when an answer can be expected after the handover, receiving organisation will change it often''
 +
 
 +
|-
 +
|18
 +
|organisation.id in API key
 +
|GET petitions.id, status
 +
|''to categorise petitions as concept, live or awaiting answer etc.''
 +
 
 +
|-
 +
|19
 +
|organisation.id in API key
 +
|POST petitions.id, status
 +
|''change the [[status]] of a petition, from staging to live, concept or rejected, from live to in_process and completed''
 +
 
 +
|-
 +
|20
 +
|organisation.id in API key
 +
|POST newsitems.title, newsitems.text, newsitems.petition_id, newsitems.officeid
 +
|''a news item about the petition, for example announce a hand over''
 +
 
 +
|-
 +
|21
 +
|organisation.id in API key, time>now
 +
| POST petitions.id, petitions.date_projected
 +
| ''the final word on the hand over date comes from the recipient who controls the agenda, not in the past''
 +
|}
  
−
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.
+
==application developers==
  
−
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.
+
Third party developers with a need for a certain new query should contact us and bring in the budget to adapt the application programming interface. Examples of potential new queries in the future:
  
−
Of een lokatie-gebaseerde app die waarschuwt dat er in de buurt waar je wandelt een petitie is om te ondertekenen.
+
* a generated petition using a template based on big data coming from certain aggregated complaints
 +
* submitting a url of a webpage with an essay that an certain number of readers recommend to reformulate as a petition, for example a newspaper article or blog posting, immediately inserting the readers as new_signatories
 +
* a location based augmented reality app showing petitions, current and old, based on GPS-data
 +
* keeping track of who you invited to sign a petition and who of your friends signed publicly
  
 
==media==
 
==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.  
+
Similar to the previous category of user, but with the distinction that these website are interested to offer relevant free content repackaged to the end-user. The goals is to sell the content with advertising or to further their activistic goals. For example a local blog (geography) or a animal rights community (thematic) or the language/dialect of a petition.
  
 +
These users will probably be best served with a RSS-feed of petitions with a certain geographic identified (recipient of petition for example) or thematic keyword ([[tag]]). A widget that can easily embed in an existing website will serve even more. This is similar to a feature for the [[Application_Programming_Interface#petitioners]] but with a different appearance. They show all the petitions relevant to a certain query, without a form to sign, but with the name and the number of signatures.
  
−
==journalisten==
+
==journalists==
  
−
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.  
+
The user with the role 'journalist' has specific, professional needs and does not mind requesting some login-id. If the journalist has been awarded a certain level of trust, then also personal information of the petitioner (not visible on the website) can be shown, although not before a petition goes live and not after the petition is closed.  
  
 +
The journalist has specific interests, depending on their employer, but these are not fixed. They change employer or topic, but they should be able to adjust their profile accordingly or support multiple profiles. Both nautical themes and local politics for a certain coastal municipality for example.
  
−
==Europetition==
+
Configuring RSS-feeds or a web-profile does not fit their workflow. Sending alerts to their mailbox does. This is significantly different from the other users because this requires a simple profile- and subscriptions management webpage.
  
−
Petities die op petities.nl beginnen moeten ook gedeeld kunnen worden met andere petitiesites in Europa. [http://europetition.petities.nl 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).
+
Investigative journalists might have more complicated (historical) queries to the database. For them the profile 'researcher' is more fit.
  
 +
==Other petitioning websites==
  
−
==onderzoekers==
+
In collaboration with other petitioning website in other European member states, petitions can be connected and cross-promoted. Read-only data is exchanged and added to each other's databases, but the number of signatures can be modified. Signatures are not exchanged in order to protect the privacy. Petitions should be manually connected after the site's moderator confirms the petitions are translated copies of one another with the same recipient.
  
−
Zijn geïnteresseerd in trends en het verzamelen van data. Privacy van ondertekenaars moet wel beschermd blijven.  
+
The same functionality can be used for petitioners that decide along the way or from the start to host a petition on a dedicated server, but still would like their petition (the text, without the signatures) shown with the number of signatures, due date and so on.  
  
 +
Anyone should be able to feed a number of signatures into the database connected to a certain petition hosted elsewhere. Ideally, the number of signatures can also be scraped or pulled from a fixed URI in a certain format (in case the other site or the petitioner can not POST). An API key is required per petition.
  
−
# GET met (petition) id + updated_at de laatste bewerking van de petitionaris in de petitie, hoe actief een petitionaris is
+
{|class=wikitable
−
# 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
+
!width=5% |number
 +
!width=5% |condition
 +
!width=45%|command
 +
!width=50%|description
 +
 
 +
|-
 +
|2
 +
|API key
 +
| GET petitions.id, petition_translations.name, locale=nl
 +
| ''name of a petition, can change''
 +
 
 +
|-
 +
|3
 +
|API key
 +
| GET petitions.id, petitions.slug
 +
| ''the part of the URL with dashes, unique for a petition (can change)''
 +
 
 +
|-
 +
|4
 +
|API key
 +
| GET petitions.id, petitions.subdomain
 +
| ''fixed unique subdomain added during moderation''
 +
 
 +
|-
 +
|5
 +
|API key
 +
| GET petitions.id, petition_translations.description, locale=nl
 +
| ''short introtext above a petition (can change)''
 +
 
 +
|-
 +
|6
 +
|API key
 +
| GET petitions.id, petition_translations.initiators, locale=nl
 +
| ''fixed description of signatories, 1st part of the petition''
 +
 
 +
|-
 +
|7
 +
|API key
 +
| GET petitions.id, petition_translations.statement, locale=nl
 +
| ''fixed observation of facts in 2nd part of petition''
 +
 
 +
|-
 +
|8
 +
|API key
 +
| GET petitions.id, petition_translations.request, locale=nl
 +
| ''fixed demand of the petition, 3rd and last part of the petition''
 +
 
 +
|-
 +
|9
 +
|API key
 +
| GET petitions.id, petitions.date_projected
 +
| ''date of hand over, changes more often as hand over approaches, also an expiration date of the petition''
 +
 
 +
|-
 +
|10
 +
|API key
 +
| GET petitions.id, organisation_id
 +
| ''recipient of petition, for example local counsil or parliament''
 +
 
 +
|-
 +
|11
 +
|API key
 +
| GET organisations.id, organisation_name
 +
| ''name of the organisation (for example bv. id=658 is parliament)''
 +
 
 +
|-
 +
|12
 +
|API key
 +
| GET organisations.id, organisation_kind
 +
|  ''district, water_county, counsil, plusregion, government, parliament, european_union, collective''
 +
 
 +
|-
 +
|13
 +
|API key
 +
| GET petitions.id, petitioner_organisation
 +
| ''organisation of the petitioner, optional.''
 +
 
 +
|-
 +
|14
 +
|API key
 +
| GET petitions.id, maps_query area
 +
| ''where the petition is situated, if applicable''
 +
 
 +
|-
 +
|15
 +
|API key
 +
| GET petitions.id, signatures_count
 +
| ''how many signatures''
 +
 
 +
|-
 +
|16
 +
|API key
 +
| GET petitions.id, number_of_signatures_on_paper
 +
|''how many signatures the petitioner claims to have collected through other means (on paper)''
 +
 
 +
|-
 +
|17
 +
|API key
 +
| GET petitions.id, answer_due_date
 +
|''when an answer can be expected after the handover, receiving organisation will change it often''
 +
 
 +
|-
 +
|18
 +
|API key
 +
|GET petitions.id, status
 +
|''to categorise petitions as concept, live or awaiting answer etc.''
 +
 
 +
|-
 +
|21
 +
|API key
 +
|GET petitions.id, petitions.date_projected
 +
|''to update the date of hand over, ''
 +
 
 +
|-
 +
|22
 +
|API key
 +
|PUT petitions.id, signatures_count
 +
|''to inject the number of petitions for a petition''
 +
|}
 +
 
 +
==researchers==
 +
 
 +
Are interested in quantative and qualitative historical trends and patterns. Unlike journalists they are not interested in the individual petitioners and signatories. The privacy of users should be sufficiently masked.
 +
 
 +
These users do not mind to identify themselves and, unlike journalists, we can ask technical skills.
 +
 
 +
They do not write to the database.
 +
 
 +
{|class=wikitable
 +
|-
 +
!width=5% |number
 +
!width=5% |condition
 +
!width=45%|command
 +
!width=50%|description
 +
 
 +
|-
 +
|2
 +
|API key
 +
| GET petitions.id, petition_translations.name, locale=nl
 +
| ''name of a petition, can change''
 +
 
 +
|-
 +
|3
 +
|API key
 +
| GET petitions.id, petitions.slug
 +
| ''the part of the URL with dashes, unique for a petition (can change)''
 +
 
 +
|-
 +
|4
 +
|API key
 +
| GET petitions.id, petitions.subdomain
 +
| ''fixed unique subdomain added during moderation''
 +
 
 +
|-
 +
|5
 +
|API key
 +
| GET petitions.id, petition_translations.description, locale=nl
 +
| ''short introtext above a petition (can change)''
 +
 
 +
|-
 +
|6
 +
|API key
 +
| GET petitions.id, petition_translations.initiators, locale=nl
 +
| ''fixed description of signatories, 1st part of the petition''
 +
 
 +
|-
 +
|7
 +
|API key
 +
| GET petitions.id, petition_translations.statement, locale=nl
 +
| ''fixed observation of facts in 2nd part of petition''
 +
 
 +
|-
 +
|8
 +
|API key
 +
| GET petitions.id, petition_translations.request, locale=nl
 +
| ''fixed demand of the petition, 3rd and last part of the petition''
 +
 
 +
|-
 +
|9
 +
|API key
 +
| GET petitions.id, petitions.date_projected
 +
| ''date of hand over, changes more often as hand over approaches, also an expiration date of the petition''
 +
 
 +
|-
 +
|10
 +
|API key
 +
| GET petitions.id, organisation_id
 +
| ''recipient of petition, for example local counsil or parliament''
 +
 
 +
|-
 +
|11
 +
|API key
 +
| GET organisations.id, organisation_name
 +
| ''name of the organisation (for example bv. id=658 is parliament)''
 +
 
 +
|-
 +
|12
 +
|API key
 +
| GET organisations.id, organisation_kind
 +
|  ''district, water_county, counsil, plusregion, government, parliament, european_union, collective''
 +
 
 +
|-
 +
|13
 +
|API key
 +
| GET petitions.id, petitioner_organisation
 +
| ''organisation of the petitioner, optional.''
 +
 
 +
|-
 +
|14
 +
|API key
 +
| GET petitions.id, maps_query area
 +
| ''where the petition is situated, if applicable''
 +
 
 +
|-
 +
|15
 +
|API key
 +
| GET petitions.id, signatures_count
 +
| ''how many signatures''
 +
 
 +
|-
 +
|16
 +
|API key
 +
| GET petitions.id, number_of_signatures_on_paper
 +
|''how many signatures the petitioner claims to have collected through other means (on paper)''
 +
 
 +
|-
 +
|17
 +
|API key
 +
| GET petitions.id, answer_due_date
 +
|''when an answer can be expected after the handover, receiving organisation will change it often''
 +
 
 +
|-
 +
|18
 +
|API key
 +
|GET petitions.id, status
 +
|''to categorise petitions as concept, live or awaiting answer etc.''
 +
 
 +
|-
 +
|24
 +
|API key
 +
|GET petitions.id, signatures_count, +time since first signature
 +
|''to analyse the history of a certain petition or draw a graphic''
 +
 
 +
|-
 +
|25
 +
|API key
 +
|GET petitions, status, +date +tag +recipient +time
 +
|''to analyse the status of petitions historically or draw a graphic''
 +
|}
  
 
[[Category:developer]]
 
[[Category:developer]]

Huidige versie van 26 feb 2020 om 13:34

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.

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


Nr. User Environment Example GET POST
1 petitioners campaign websites, social networks plasticsoup.org x x
2 governments raadsinformatiesystemen, government website SIM groep, MSI, Notubiz, Gemeenteoplossingen, CompanyWebcast? x x
3 application developers mobile apps, third party sites Tippiq x
4 media news websites ANP x
5 journalists investigative news reports Sargasso, VVOJ x
6 European partners connected Europe wide petitions, European Citizens' Initiatives OpenPetition, Petitie.be x x
7 researchers statistische software, issue mapping Rathenau Instituut, Universiteit Twente, Universiteit Tilburg, HowAboutYou x

The base URI for an API call is to be announced, but the call itself (for API version 1) will start with /api/v1/ followed by the actual POST or GET command. The commands in the table below are referring to the database queries for which the precise API call is not yet known.

petitioners

These use cases are to be made possible for a petitioner/campaigner:

  • show a widget on a third party campaign website where the petition can be signed (BASIC FEATURE)
  • show a counter with the number of signatures for the petition so far (BASIC FEATURE)
  • inject the name, city and e-mailaddress as a signature by following a customised, personalised link from an e-mail newsletter (BASIC FEATURE)
  • embed a selection of petitions to promote/discuss on your personal blog (NICE FEATURE, variation on 1st)
  • create a graphic with signatures per hour or per day within a chosen time frame, e.g. 'the past days', 'when we came on tv', 'the days after the launch', 'in the different seasons last year', 'around lunch time on weekdays'(NICE TO HAVE, variation on 2nd)
  • (bonus: show an up-to-date timeline with date of start, hand over of and expected answer to the petition) (BONUS, date of start not recorded)
number condition command description
1 petitions.id, petitions.status=live POST petitions.id, new_signatures.person_name, new_signatures.person_email, new_signatures.person_city, new_signatures.visibility a signature
2 NOT NULL GET petitions.id, petition_translations.name, locale=nl name of a petition, can change
3 NOT NULL GET petitions.id, petitions.slug the part of the URL with dashes, unique for a petition (can change)
4 NOT NULL GET petitions.id, petitions.subdomain fixed unique subdomain added during moderation
5 NOT NULL GET petitions.id, petition_translations.description, locale=nl short introtext above a petition (can change)
6 NOT NULL GET petitions.id, petition_translations.initiators, locale=nl fixed description of signatories, 1st part of the petition
7 NOT NULL GET petitions.id, petition_translations.statement, locale=nl fixed observation of facts in 2nd part of petition
8 NOT NULL GET petitions.id, petition_translations.request, locale=nl fixed demand of the petition, 3rd and last part of the petition
9 NOT NULL GET petitions.id, petitions.date_projected date of hand over, changes more often as hand over approaches, also an expiration date of the petition
10 NOT NULL GET petitions.id, organisation_id recipient of petition, for example local counsil or parliament
11 GET organisations.id, organisation_name name of the organisation (for example bv. id=658 is parliament)
12 GET organisations.id, organisation_kind district, water_county, counsil, plusregion, government, parliament, european_union, collective
13 NOT NULL GET petitions.id, petitioner_organisation organisation of the petitioner, optional.
14 NOT NULL GET petitions.id, maps_query area where the petition is situated, if applicable
15 NOT NULL GET petitions.id, signatures_count how many signatures
16 NOT NULL GET petitions.id, number_of_signatures_on_paper how many signatures the petitioner claims to have collected through other means (on paper)
17 NOT NULL GET petitions.id, answer_due_date when an answer can be expected after the handover, receiving organisation will change it often

governments

In addition to the use cases for the petitioner, these are to be made possible for local governments

  • show petitions in an app or website specific for some locality/recipient (BASIC FEATURE)
  • change the status of a petition (BASIC FEATURE)
  • add a formal case number for a petition upon reception (BASIC FEATURE)
  • embed petitions for the citizenry of a locality on a website
  • link existing formal documents as related to the petition
  • show citizen engagement with statistics (number of signatures, subscriptions to updates)
  • show deadlines for petitions (hand over, answer, public hearing, committee meetings, etc.)
  • post news updates connected to petitions
number condition command description
2 organisation.id in API key GET petitions.id, petition_translations.name, locale=nl name of a petition, can change
6 organisation.id in API key GET petitions.id, petition_translations.initiators, locale=nl fixed description of signatories, 1st part of the petition
7 organisation.id in API key GET petitions.id, petition_translations.statement, locale=nl fixed observation of facts in 2nd part of petition
8 organisation.id in API key GET petitions.id, petition_translations.request, locale=nl fixed demand of the petition, 3rd and last part of the petition
9 organisation.id in API key GET petitions.id, petitions.date_projected date of hand over, changes more often as hand over approaches, also an expiration date of the petition
10 organisation.id in API key GET petitions.id, organisation_id recipient of petition, for example local counsil or parliament
13 organisation.id in API key GET petitions.id, petitioner_organisation organisation of the petitioner, optional.
14 organisation.id in API key GET petitions.id, maps_query area where the petition is situated, if applicable
15 organisation.id in API key GET petitions.id, signatures_count how many signatures
16 organisation.id in API key GET petitions.id, number_of_signatures_on_paper how many signatures the petitioner claims to have collected through other means (on paper)
17 organisation.id in API key GET petitions.id, answer_due_date when an answer can be expected after the handover, receiving organisation will change it often
18 organisation.id in API key GET petitions.id, status to categorise petitions as concept, live or awaiting answer etc.
19 organisation.id in API key POST petitions.id, status change the status of a petition, from staging to live, concept or rejected, from live to in_process and completed
20 organisation.id in API key POST newsitems.title, newsitems.text, newsitems.petition_id, newsitems.officeid a news item about the petition, for example announce a hand over
21 organisation.id in API key, time>now POST petitions.id, petitions.date_projected the final word on the hand over date comes from the recipient who controls the agenda, not in the past

application developers

Third party developers with a need for a certain new query should contact us and bring in the budget to adapt the application programming interface. Examples of potential new queries in the future:

  • a generated petition using a template based on big data coming from certain aggregated complaints
  • submitting a url of a webpage with an essay that an certain number of readers recommend to reformulate as a petition, for example a newspaper article or blog posting, immediately inserting the readers as new_signatories
  • a location based augmented reality app showing petitions, current and old, based on GPS-data
  • keeping track of who you invited to sign a petition and who of your friends signed publicly

media

Similar to the previous category of user, but with the distinction that these website are interested to offer relevant free content repackaged to the end-user. The goals is to sell the content with advertising or to further their activistic goals. For example a local blog (geography) or a animal rights community (thematic) or the language/dialect of a petition.

These users will probably be best served with a RSS-feed of petitions with a certain geographic identified (recipient of petition for example) or thematic keyword (tag). A widget that can easily embed in an existing website will serve even more. This is similar to a feature for the Application_Programming_Interface#petitioners but with a different appearance. They show all the petitions relevant to a certain query, without a form to sign, but with the name and the number of signatures.

journalists

The user with the role 'journalist' has specific, professional needs and does not mind requesting some login-id. If the journalist has been awarded a certain level of trust, then also personal information of the petitioner (not visible on the website) can be shown, although not before a petition goes live and not after the petition is closed.

The journalist has specific interests, depending on their employer, but these are not fixed. They change employer or topic, but they should be able to adjust their profile accordingly or support multiple profiles. Both nautical themes and local politics for a certain coastal municipality for example.

Configuring RSS-feeds or a web-profile does not fit their workflow. Sending alerts to their mailbox does. This is significantly different from the other users because this requires a simple profile- and subscriptions management webpage.

Investigative journalists might have more complicated (historical) queries to the database. For them the profile 'researcher' is more fit.

Other petitioning websites

In collaboration with other petitioning website in other European member states, petitions can be connected and cross-promoted. Read-only data is exchanged and added to each other's databases, but the number of signatures can be modified. Signatures are not exchanged in order to protect the privacy. Petitions should be manually connected after the site's moderator confirms the petitions are translated copies of one another with the same recipient.

The same functionality can be used for petitioners that decide along the way or from the start to host a petition on a dedicated server, but still would like their petition (the text, without the signatures) shown with the number of signatures, due date and so on.

Anyone should be able to feed a number of signatures into the database connected to a certain petition hosted elsewhere. Ideally, the number of signatures can also be scraped or pulled from a fixed URI in a certain format (in case the other site or the petitioner can not POST). An API key is required per petition.

number condition command description
2 API key GET petitions.id, petition_translations.name, locale=nl name of a petition, can change
3 API key GET petitions.id, petitions.slug the part of the URL with dashes, unique for a petition (can change)
4 API key GET petitions.id, petitions.subdomain fixed unique subdomain added during moderation
5 API key GET petitions.id, petition_translations.description, locale=nl short introtext above a petition (can change)
6 API key GET petitions.id, petition_translations.initiators, locale=nl fixed description of signatories, 1st part of the petition
7 API key GET petitions.id, petition_translations.statement, locale=nl fixed observation of facts in 2nd part of petition
8 API key GET petitions.id, petition_translations.request, locale=nl fixed demand of the petition, 3rd and last part of the petition
9 API key GET petitions.id, petitions.date_projected date of hand over, changes more often as hand over approaches, also an expiration date of the petition
10 API key GET petitions.id, organisation_id recipient of petition, for example local counsil or parliament
11 API key GET organisations.id, organisation_name name of the organisation (for example bv. id=658 is parliament)
12 API key GET organisations.id, organisation_kind district, water_county, counsil, plusregion, government, parliament, european_union, collective
13 API key GET petitions.id, petitioner_organisation organisation of the petitioner, optional.
14 API key GET petitions.id, maps_query area where the petition is situated, if applicable
15 API key GET petitions.id, signatures_count how many signatures
16 API key GET petitions.id, number_of_signatures_on_paper how many signatures the petitioner claims to have collected through other means (on paper)
17 API key GET petitions.id, answer_due_date when an answer can be expected after the handover, receiving organisation will change it often
18 API key GET petitions.id, status to categorise petitions as concept, live or awaiting answer etc.
21 API key GET petitions.id, petitions.date_projected to update the date of hand over,
22 API key PUT petitions.id, signatures_count to inject the number of petitions for a petition

researchers

Are interested in quantative and qualitative historical trends and patterns. Unlike journalists they are not interested in the individual petitioners and signatories. The privacy of users should be sufficiently masked.

These users do not mind to identify themselves and, unlike journalists, we can ask technical skills.

They do not write to the database.

number condition command description
2 API key GET petitions.id, petition_translations.name, locale=nl name of a petition, can change
3 API key GET petitions.id, petitions.slug the part of the URL with dashes, unique for a petition (can change)
4 API key GET petitions.id, petitions.subdomain fixed unique subdomain added during moderation
5 API key GET petitions.id, petition_translations.description, locale=nl short introtext above a petition (can change)
6 API key GET petitions.id, petition_translations.initiators, locale=nl fixed description of signatories, 1st part of the petition
7 API key GET petitions.id, petition_translations.statement, locale=nl fixed observation of facts in 2nd part of petition
8 API key GET petitions.id, petition_translations.request, locale=nl fixed demand of the petition, 3rd and last part of the petition
9 API key GET petitions.id, petitions.date_projected date of hand over, changes more often as hand over approaches, also an expiration date of the petition
10 API key GET petitions.id, organisation_id recipient of petition, for example local counsil or parliament
11 API key GET organisations.id, organisation_name name of the organisation (for example bv. id=658 is parliament)
12 API key GET organisations.id, organisation_kind district, water_county, counsil, plusregion, government, parliament, european_union, collective
13 API key GET petitions.id, petitioner_organisation organisation of the petitioner, optional.
14 API key GET petitions.id, maps_query area where the petition is situated, if applicable
15 API key GET petitions.id, signatures_count how many signatures
16 API key GET petitions.id, number_of_signatures_on_paper how many signatures the petitioner claims to have collected through other means (on paper)
17 API key GET petitions.id, answer_due_date when an answer can be expected after the handover, receiving organisation will change it often
18 API key GET petitions.id, status to categorise petitions as concept, live or awaiting answer etc.
24 API key GET petitions.id, signatures_count, +time since first signature to analyse the history of a certain petition or draw a graphic
25 API key GET petitions, status, +date +tag +recipient +time to analyse the status of petitions historically or draw a graphic
Overgenomen van "https://handboek.petities.nl/mediawiki/index.php?title=Application_Programming_Interface&oldid=6466"