-
Notifications
You must be signed in to change notification settings - Fork 12
How to use API
Pierre Bellon edited this page Oct 31, 2013
·
52 revisions
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 authenticated. The first thing you need to do for authentication is to have a superuser on your application. To do that check the [add a superuser][add-a-superuser] wiki page.
When your superuser is set up you should be able to create new users on your database. Create at least one user for your API or use the superuser of your app (strongly discouraged).
Simple Authentication works by passing an encoded version of the user credentials.
To get access to reserved method of endpoints you need to add the proper Authorization
in every HTTP's request header.
Here is an example of how you should use the Authorization header variable using
base64 as tool for encoding the user:pass string into Base64.
curl -X DELETE localhost:8000/api/stories/80/ -H "Authorization: Basic $(echo -n 'user:pass'|base64)"DELETE /api/stories/80/ HTTP/1.1
User-Agent: curl/7.29.0
Host: localhost:8000
Accept: */*
Authorization: Basic dXNlcjpwYXNz
``
### Token Auth
This is our recommended authentication method. To use it you have to create/get a
session token on the `/api/api-token-auth/` API endpoint.
#### Example
1. First create/get your session token:
```sh
curl -X POST localhost:8000/api/api-token-auth/ -d '{ "username":"user", "password":"pass" }' -H "Content-Type: application/json"
```
HTTP Request:
```http
POST /api/api-token-auth/ HTTP/1.1
User-Agent: curl/7.29.0
Host: localhost:8000
Accept: */*
Content-Type: application/json
Content-Length: 41
```
HTTP Response:
```http
HTTP/1.0 200 OK
Date: Thu, 31 Oct 2013 13:18:27 GMT
Server: WSGIServer/0.1 Python/2.7.4
Vary: Accept, Cookie
Content-Type: application/json
Allow: POST, OPTIONS
{"token": "10ng70k3n1s10ng"}%
```
> TIP: this is not a real token.
2. Use this token in HTTP's header:
```sh
curl -X DELETE localhost:8000/api/stories/265/ -H 'Authorization: Token 10ng70k3n1s10ng'
```
```http
HTTP Request:
DELETE /api/stories/265/ HTTP/1.1
User-Agent: curl/7.29.0
Host: localhost:8000
Accept: */*
Authorization: Token 10ng70k3n1s10ng
```
HTTP Response:
```http
HTTP/1.0 204 NO CONTENT
Date: Thu, 31 Oct 2013 13:27:04 GMT
Server: WSGIServer/0.1 Python/2.7.4
Vary: Accept, Cookie
Content-Length: 0
Content-Type: application/json
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
```
### X-CSRF Token
To avoid
## Entities
### Stories
Stories are the central entities of our application. For further informations about [stories](/jplusplus/okf-spending-stories/wiki/About-this-project#stories).
- [Stories attributes](/jplusplus/okf-spending-stories/wiki/How-to-use-API#stories-attributes)
- Endpoints
- [`/api/stories/`][apistories]
- [`/api/stories/:id/`][apistoriesid]
- [`/api/stories-nested/`][apistories-nested]
- [`/api/stories-nested/:id/`][apistories-nestedid]
- [How to filter results][how-to-filter-results]
- [Get stories sorted by relevance][get-results-filtered-by-relevance]
#### Stories attributes
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](http://tools.ietf.org/html/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` | ✗ |
#### Endpoints
##### `/api/stories/`
> GET, POST, HEAD, OPTIONS
List all stories in our application.
##### `/api/stories/:id/`
> GET, PUT, DELETE, HEAD, OPTIONS, PATCH
Return a single story.
##### `/api/stories-nested/`
> GET, POST, HEAD, OPTIONS
Similar as [`/api/stories/`][apistories] except that it's in a nested mode.
That means every related object (like themes, country or currency) will be
returned as well.
##### `/api/stories-nested/:id/`
> GET, PUT, DELETE, HEAD, OPTIONS, PATCH
Return a single story and its nested objects.
#### How to filter results?
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/][apicountries] for more details. |
| **currency** | `String` | Will filter stories based on the given currency | The iso code of the wanted currency, see [/api/currencies/][apicurrencies] for more details. |
| **type** | `String` | Will filter stories based on their type. | `over_one_year`, `discrete`, see [stories][stories] for more details about story types. |
| **title** | `String` | Will filter stories based on their title | Title of an existing story |
| **themes** | `String` | Will filter stories based on their theme(s). | Slug(s) of one or more themes |
#### Get results filtered by relevance
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
A theme can be compared as a category for every [story](/jplusplus/okf-spending-stories/wiki/About-this-project#stories).
- [Themes attributes][themes-attributes]
- Endpoints
- [`/api/themes/`][apithemes]
- [`/api/themes/:slug/`][apithemesslug]
#### Themes attributes
| 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/`][apithemesslug]) | `'aid'` | ✗ |
| **description** | `String` | Theme's title | `'Humanitarian aid'` | ✗ |
| **image** | `String` | Theme's image URL | `'https://<your static server address>/themes/aid.svg'` | ✗ |
#### Endpoints
##### `/api/themes/`
> GET, HEAD, OPTIONS
List all themes.
##### `/api/themes/:slug/`
> GET, HEAD, OPTIONS
Get one single theme using its `slug`.
### Currencies
This entity is not representative of every currency in the world. Nonetheless we chosed
to store in our API a list of the most used currencies.
Checkout the [inflation][inflation] wiki
page to learn more about currencies & how they are important in our application.
- [Currencies attributes][currencies-attributes]
- Endpoints
- [`/api/currencies/`][apicurrencies]
- [`/api/currencies/:id/`][apicurrenciesid]
#### Currencies attributes
| Name | Type | Description | Example | Writable ? |
| :----: | ---- | ----------- | ------- | :--------: |
| **iso_code** | `String` | Currency's ISO code | `'USD'` | ✗ |
| **name** | `String` | Currency's name | `'US Dollar'` | ✗ |
| **rate** | `Float` | The currency conversion rate to USD | `1` | ✗ |
| **symbol** | `String` | The unicode symbol(s) for this currency (if exists) | `'$'` | ✗ |
| **priority** | `Integer` | Arbitrary priority for this currency over other ones | `3` | ✗ |
#### `/api/currencies/`
> GET, HEAD, OPTIONS
List all currencies.
#### `/api/currencies/:id/`
> GET, HEAD, OPTIONS
### Countries
Countries are useful to compute the inflation.
Checkout [inflation](/jplusplus/okf-spending-stories/wiki/About-this-project#inflation) to learn
more about how we compute inflation.
- [Countries attributes][countries-attributes]
- Endpoints
- [`/api/countries/`][apicountries]
#### Countries attributes
| Name | Type | Description | Example | Writable ? |
| :----: | ---- | ----------- | ------- | :--------: |
| **iso_code** | `String` | Country's ISO code | `'USA'` | ✗ |
| **name** | `String` | Country's name | `'United States of America' | ✗ |
#### `/api/countries/`
> GET, HEAD, OPTIONS
[stories]: /jplusplus/okf-spending-stories/wiki/About-this-project#stories
[inflation]: /jplusplus/okf-spending-stories/wiki/About-this-project#inflation
[stories-attributes]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#stories-attributes
[howtofilterresults]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#how-to-filter-results)
[how-to-filter-results]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#how-to-filter-results
[get-results-filtered-by-relevance]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#get-results-filtered-by-relevance
[countries-attributes]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#countries-attributes
[currencies-attributes]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#currencies-attributes
[themes-attributes]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#themes-attributes
[apistories]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#apistories
[apistories]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#apistories
[apistoriesid]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#apistoriesid
[apistories-nested]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#apistories-nested
[apistories-nestedid]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#apistories-nestedid
[apithemesslug]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#apithemesslug
[apicurrencies]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#apicurrencies
[apicurrenciesid]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#apicurrenciesid
[apicountries]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#apicountries
[apithemes]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#apithemes
[apithemesslug]: /jplusplus/okf-spending-stories/wiki/How-to-use-API#apithemesslug