-
Notifications
You must be signed in to change notification settings - Fork 12
How to use API
Spending Stories API supports HTML & JSON format as output.
Checkout http://<your server host>/api/ on your server to browse and use the API.
Some of the operation (flagged with *) require to be authenficated. This part explains how to use the auth.
Spending Stories authentifcation system is based on a simple token auth.
Stories are the central entities of our application. For further informations about stories.
Every story is composed of the following attributes:
| Name | Type | Description | Example | Writable ? |
|---|---|---|---|---|
| id | Integer |
Story identifier | 210 |
✗ |
| value | Float |
Spending amount | 1563.0 |
✓ |
| tite | String |
Story's title | "A title" |
✓ |
| description | String |
Story description | "A description" |
✓ |
| country | String |
ISO code of story's country | FRA |
✓ |
| currency | String |
ISO code of story's currency | FRA |
✓ |
| year | Integer |
Story year | 2010 |
✓ |
| themes | Array |
Related themes of this story. | ['aid', 'health' ] |
✓ |
| type | String |
Story description | over_one_year |
✓ |
| sticky | Boolean |
Story sticky status | true |
Staff Only |
| created_at | String |
Story creation date encoded with RFC3339 format | "2013-08-08T09:18:45.816Z" |
✗ |
| current_value | Float |
Compensated value of the story (in its own currency) | 1607.10332334703 |
✗ |
| current_value_usd | Float |
Converted compensated value of story in USD. | 2442.0536903441 |
✗ |
| inflation_last_year | Integer |
Last avalaible year of inflation for this story | 10e6 |
✗ |
GET, POST, HEAD, OPTIONS
List all stories in our application.
GET, PUT, DELETE, HEAD, OPTIONS, PATCH
Return a single story.
GET, POST, HEAD, OPTIONS
Similar as /api/stories/ except
that it's in a nested mode. That means every related object (like themes, country or currency) will
be return as well.
GET, PUT, DELETE, HEAD, OPTIONS, PATCH
Return a single story and its nested objects.
Results can be filtered using the following fields:
| Name | Type | Description | Possible values |
|---|---|---|---|
| sticky | Boolean |
Will filter stories based on their sticky attribute. |
True,False,''
|
| country | String |
Will filter stories based on the given country | The iso code of the wanted country, see /api/countries/ for more details. |
| currency | String |
Will filter stories based on the given currency | The iso code of the wanted currency, see /api/currencies/ for more details. |
| type | String |
Will filter stories based on their type. |
over_one_year, discrete, see the wiki page for more details. |
| title | String |
Will filter stories based on their title | Title of an existing story |
| themes | String |
Will filter stories based on their theme(s). |
An extra method exists for stories. /api/stories/ and /api/stories-nested/ endpoints can be requested with an extra parameter called relevance_for.
It takes an integer or a float as parameter and correspond to an amount in USD.
It will return a list of stories that are relevant compared to this amount. Check what is a relevant story wiki page to learn more about our relevance model.
- Themes attributes
- Endpoints
A theme can be compared as a category for every story
| Name | Type | Description | Example | Writable ? |
|---|---|---|---|---|
| title | String |
Theme's title | 'Aid' |
✗ |
| slug | String |
Theme's slug, can be used to get a single theme (check /api/themes/:slug/) |
'aid' |
✗ |
| description | String |
Theme's title | 'Humanitarian aid' |
✗ |
| image | String |
Theme's image URL | 'https://<your static server address>/themes/aid.svg' |
✗ |
GET, HEAD, OPTIONS
List all themes.
GET, HEAD, OPTIONS
Get one single theme using its slug.
GET, HEAD, OPTIONS
GET, HEAD, OPTIONS
GET, HEAD, OPTIONS
GET, HEAD, OPTIONS