From 2134bde3ef83245d45a59cd8996e67732c0f5e6e Mon Sep 17 00:00:00 2001 From: Chris Mytton Date: Mon, 14 Apr 2014 11:02:39 +0100 Subject: [PATCH] Move Popolo extensions section further down We don't want to confuse the user with advanced topics before we've explained the basics. --- docs/api.md | 100 ++++++++++++++++++++++++++-------------------------- 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/docs/api.md b/docs/api.md index 8e335ae2..b4892609 100644 --- a/docs/api.md +++ b/docs/api.md @@ -14,56 +14,6 @@ There is a version string in the API url, currently `v0.1`. This will be updated All textual entries stored in PopIt follow the [Popolo](http://popoloproject.com/) schema. You can also add additional fields on top of this using the admin interface or the API. -### Popolo extensions - -In addition to the [Popolo schemas](http://popoloproject.com/specs/) we have added some PopIt specific customisations. - -#### Area objects - -An area object on Memberships and Posts: this allows you to store the name and id of an area that relates to the Membership or Post that it appears in. You can put any string value in the id field, but the most common use case is to put a [MapIt](http://mapit.mysociety.org/) url there. For example if you wanted to associate a Post with an area: - -```json -{ - "label": "MP for Witney", - "area": { - "id": "http://mapit.mysociety.org/area/65622", - "name": "Witney (UK Parliament constituency)" - } -} -``` - -#### Organization memberships - -Popolo currently only allows the members of an Organization to be Persons, but we've extended this to allow them to also be other Organizations. This allows you to e.g. model coalitions. The party Organizations which are part of the coalition have Memberships connecting them to the coalition Organization. - -An example Membership modelling The Conservative Party's Membership in the UK's Cameron Ministry coalition might look something like: - -```json -{ - "organization_id": "cameron_ministry", - "member": { - "@type": "Organization", - "id": "conservative_party" - } -} -``` - -Then the Liberal Democrats' Membership would look something like: - -```json -{ - "organization_id": "cameron_ministry", - "member": { - "@type": "Organization", - "id": "liberal_democrats" - } -} -``` - -Where `cameron_ministry` is the id of the coalition Organization and `conservative_party` and `liberal_democrats` are the ids of the parties in the coalition. - -When the API returns the `conservative_party` or `liberal_democrats` record, the `memberships` array property will include the Membership to the coalition. Likewise when the API returns the `cameron_ministry` record the `memberships` array property will include the Memberships to the two parties' Organizations. - ## API collections The API allows you to query four types of collection, **persons**, **organizations**, **memberships** and **posts**. Anywhere in the documentation you see `:collection` you can replace it with one of those four types. @@ -165,6 +115,56 @@ An object is determined to be a translation object if all of the keys are valid When indexing multiple languages each translation is stored in a separate string key. So for the example above the English and Russian translations would be stored in `name_en` and `name_ru` respectively. So to search for a name in Russian you can use a query like `name_ru:Джон`. The `name` key will still exist, but will only contain the default language. +### Popolo extensions + +In addition to the [Popolo schemas](http://popoloproject.com/specs/) we have added some PopIt specific customisations. + +#### Area objects + +An area object on Memberships and Posts: this allows you to store the name and id of an area that relates to the Membership or Post that it appears in. You can put any string value in the id field, but the most common use case is to put a [MapIt](http://mapit.mysociety.org/) url there. For example if you wanted to associate a Post with an area: + +```json +{ + "label": "MP for Witney", + "area": { + "id": "http://mapit.mysociety.org/area/65622", + "name": "Witney (UK Parliament constituency)" + } +} +``` + +#### Organization memberships + +Popolo currently only allows the members of an Organization to be Persons, but we've extended this to allow them to also be other Organizations. This allows you to e.g. model coalitions. The party Organizations which are part of the coalition have Memberships connecting them to the coalition Organization. + +An example Membership modelling The Conservative Party's Membership in the UK's Cameron Ministry coalition might look something like: + +```json +{ + "organization_id": "cameron_ministry", + "member": { + "@type": "Organization", + "id": "conservative_party" + } +} +``` + +Then the Liberal Democrats' Membership would look something like: + +```json +{ + "organization_id": "cameron_ministry", + "member": { + "@type": "Organization", + "id": "liberal_democrats" + } +} +``` + +Where `cameron_ministry` is the id of the coalition Organization and `conservative_party` and `liberal_democrats` are the ids of the parties in the coalition. + +When the API returns the `conservative_party` or `liberal_democrats` record, the `memberships` array property will include the Membership to the coalition. Likewise when the API returns the `cameron_ministry` record the `memberships` array property will include the Memberships to the two parties' Organizations. + ## Examples To view a list of all the people (**persons**) in the database: