Application Programming Interface: verschil tussen versies
(→application developers) |
(GO erbij) |
||
| Regel 31: | Regel 31: | ||
|governments | |governments | ||
|raadsinformatiesystemen, government website | |raadsinformatiesystemen, government website | ||
| − | |SIM groep, MSI, Notubiz, CompanyWebcast? | + | |SIM groep, MSI, Notubiz, Gemeenteoplossingen, CompanyWebcast? |
|x | |x | ||
|x | |x | ||
Versie van 5 okt 2017 om 11:03
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, 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 |
Inhoud
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)
- 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 newsitems.title, newsitems.text, newsitems.petition_id, newsitems.officeid | a news item about the petition, for example announce a hand over |
| 20 | 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 coming 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
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.
- GET met (petition) id + updated_at de laatste bewerking van de petitionaris in de petitie, hoe actief een petitionaris is
- 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
