Application Programming Interface: verschil tussen versies

Uit Petities
Ga naar: navigatie, zoeken
(petitioners: numbered)
(petitioners: condition added)
Regel 91: Regel 91:
 
|-
 
|-
 
!width=5% |number
 
!width=5% |number
 +
!width=5% |condition
 
!width=45%|command
 
!width=45%|command
 
!width=50%|description
 
!width=50%|description
Regel 96: Regel 97:
 
|-
 
|-
 
|1
 
|1
 +
|petitions.status=live
 
|POST new_signatures.person_name, new_signatures.person_email, new_signatures.person_city, new_signatures.visibility  
 
|POST new_signatures.person_name, new_signatures.person_email, new_signatures.person_city, new_signatures.visibility  
 
| ''a signature''
 
| ''a signature''
Regel 101: Regel 103:
 
|-
 
|-
 
|2
 
|2
 +
|NOT NULL
 
| GET petitions.id, petition_translations.name, locale=nl
 
| GET petitions.id, petition_translations.name, locale=nl
 
| ''name of a petition, can change''
 
| ''name of a petition, can change''
Regel 106: Regel 109:
 
|-
 
|-
 
|3
 
|3
 +
|NOT NULL
 
| GET petitions.id, petitions.slug
 
| GET petitions.id, petitions.slug
 
| ''the part of the URL with dashes, unique for a petition (can change)''
 
| ''the part of the URL with dashes, unique for a petition (can change)''
Regel 111: Regel 115:
 
|-
 
|-
 
|4
 
|4
 +
|NOT NULL
 
| GET petitions.id, petitions.subdomain
 
| GET petitions.id, petitions.subdomain
 
| ''fixed unique subdomain added during moderation''
 
| ''fixed unique subdomain added during moderation''
Regel 116: Regel 121:
 
|-
 
|-
 
|5
 
|5
 +
|NOT NULL
 
| GET petitions.id, petition_translations.description, locale=nl
 
| GET petitions.id, petition_translations.description, locale=nl
 
| ''short introtext above a petition (can change)''
 
| ''short introtext above a petition (can change)''
Regel 121: Regel 127:
 
|-
 
|-
 
|6
 
|6
 +
|NOT NULL
 
| GET petitions.id, petition_translations.initiators, locale=nl
 
| GET petitions.id, petition_translations.initiators, locale=nl
 
| ''fixed description of signatories, 1st part of the petition''
 
| ''fixed description of signatories, 1st part of the petition''
Regel 126: Regel 133:
 
|-
 
|-
 
|7
 
|7
 +
|NOT NULL
 
| GET petitions.id, petition_translations.statement, locale=nl
 
| GET petitions.id, petition_translations.statement, locale=nl
 
| ''fixed observation of facts in 2nd part of petition''
 
| ''fixed observation of facts in 2nd part of petition''
Regel 131: Regel 139:
 
|-
 
|-
 
|8
 
|8
 +
|NOT NULL
 
| GET petitions.id, petition_translations.request, locale=nl
 
| GET petitions.id, petition_translations.request, locale=nl
 
| ''fixed demand of the petition, 3rd and last part of the petition''
 
| ''fixed demand of the petition, 3rd and last part of the petition''
Regel 136: Regel 145:
 
|-
 
|-
 
|9
 
|9
 +
|NOT NULL
 
| GET petitions.id, petitions.date_projected
 
| GET petitions.id, petitions.date_projected
 
| ''date of hand over, changes more often as hand over approaches, also an expiration date of the petition''
 
| ''date of hand over, changes more often as hand over approaches, also an expiration date of the petition''
Regel 141: Regel 151:
 
|-
 
|-
 
|10
 
|10
 +
|NOT NULL
 
| GET petitions.id, organisation_id
 
| GET petitions.id, organisation_id
 
| ''recipient of petition, for example local counsil or parliament''
 
| ''recipient of petition, for example local counsil or parliament''
Regel 146: Regel 157:
 
|-
 
|-
 
|11
 
|11
 +
|
 
| GET organisations.id, organisation_name
 
| GET organisations.id, organisation_name
 
| ''name of the organisation (for example bv. id=658 is parliament)''
 
| ''name of the organisation (for example bv. id=658 is parliament)''
Regel 151: Regel 163:
 
|-
 
|-
 
|12
 
|12
 +
|
 
| GET organisations.id, organisation_kind
 
| GET organisations.id, organisation_kind
 
|  ''district, water_county, counsil, plusregion, government, parliament, european_union, collective''
 
|  ''district, water_county, counsil, plusregion, government, parliament, european_union, collective''
Regel 156: Regel 169:
 
|-
 
|-
 
|13
 
|13
 +
|NOT NULL
 
| GET petitions.id, petitioner_organisation
 
| GET petitions.id, petitioner_organisation
 
| ''organisation of the petitioner, optional.''
 
| ''organisation of the petitioner, optional.''
Regel 161: Regel 175:
 
|-
 
|-
 
|14
 
|14
 +
|NOT NULL
 
| GET petitions.id, maps_query area
 
| GET petitions.id, maps_query area
 
| ''where the petition is situated, if applicable''  
 
| ''where the petition is situated, if applicable''  
Regel 166: Regel 181:
 
|-
 
|-
 
|15
 
|15
 +
|NOT NULL
 
| GET petitions.id, signatures_count  
 
| GET petitions.id, signatures_count  
 
| ''how many signatures''
 
| ''how many signatures''
Regel 171: Regel 187:
 
|-
 
|-
 
|16
 
|16
 +
|NOT NULL
 
| GET petitions.id, number_of_signatures_on_paper
 
| GET petitions.id, number_of_signatures_on_paper
 
|''how many signatures the petitioner claims to have collected through other means (on paper)''
 
|''how many signatures the petitioner claims to have collected through other means (on paper)''
Regel 176: Regel 193:
 
|-
 
|-
 
|17
 
|17
 +
|NOT NULL
 
| GET petitions.id, answer_due_date  
 
| GET petitions.id, answer_due_date  
 
|''when an answer can be expected after the handover, receiving organisation will change it often''
 
|''when an answer can be expected after the handover, receiving organisation will change it often''

Versie van 28 sep 2017 om 12:10

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. User Environment Example GET POST
1 petitioners campaign websites, social networks plasticsoup.org x x
2 governments raadsinformatiesystemen, government website SIM groep, MSI, Notubiz, 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


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.status=live POST 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

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

application developers

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.

Of een toepassing (app of site) waarbij je kan zien wie van je vrienden wel eens een petitie publiekelijk hebben ondertekend zodat je ze makkelijk uit kan nodigen om de petities die je zelf hebt ondertekend ook te tekenen. Of om te zien of je die petities zelf wilt tekenen of wilt bespreken met ze.

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.


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.


European partners

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


researchers

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