diff --git a/source/index.html.md b/source/index.html.md
index bcb5c79d15b..723367cc0c8 100644
--- a/source/index.html.md
+++ b/source/index.html.md
@@ -3,9 +3,6 @@ title: API Reference
language_tabs: # must be one of https://git.io/vQNgJ
- shell
- - ruby
- - python
- - javascript
toc_footers:
- Sign Up for a Developer Key
@@ -25,40 +22,18 @@ meta:
# Introduction
-Welcome to the Padam API! You can use our API to access Padam API endpoints, *which can get information on various
-cats, kittens, and breeds in our database* (**TODO**).
-
-We have language bindings in Shell, Java, Python, and JavaScript! You can view code examples in the dark area to the
-right, and you can switch the programming language of the examples with the tabs in the top right.
+Welcome to the Padam API! You can use our API to access Padam API endpoints.
# Authentication
> To authorize, use this code:
-```ruby
-require 'kittn'
-
-api = Kittn::APIClient.authorize!('secret')
-```
-
-```python
-import padam
-
-api = padam.authorize('secret')
-```
-
```shell
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
-H "Authorization: secret"
```
-```javascript
-const padam = require('padam');
-
-let api = padam.authorize('secret');
-```
-
> Make sure to replace `secret` with your API key.
Padam uses API keys to allow access to the API. You can register a new Padam API key at our
@@ -73,19 +48,82 @@ following:
You must replace secret with your personal API key.
+# About the API
+
+## Dates
+
+In the Padam API, any date are formatted, as strings, by using the
+[ISO 8601 international standard](https://en.wikipedia.org/wiki/ISO_8601).
+
+As an example, the 2022, 17th of march, at noon can be written as following (in UTC):
+ - `"2022-03-17T13:44:49+00:00"`
+
+
+
+## Pagination
+
+Most of the collections of resources that are returned by the Padam API are paginated. In order to ease the display of
+the results for frontend application, we use a Page Number Pagination.
+
+See also: [Page Number Pagination with DRF](https://www.django-rest-framework.org/api-guide/pagination/#pagenumberpagination)
+
+> Here is how to query a paginated endpoint
+
+```shell
+# The page parameter is optional. If not given, its value is `1`
+curl "https://api.example.org/nodes/?page=4" \
+ -H "Authorization: secret"
+```
+
+> Here is a sample of a paginated endpoint output. Results are located under the `results` key, which is an array.
+
+```json
+{
+ "count": 1023,
+ "next": "https://api.example.org/accounts/?page=5",
+ "previous": "https://api.example.org/accounts/?page=3",
+ "results": [
+ ]
+}
+```
+
# Nodes
-## Search among nodes
+A node is the representation of a location. It is represented by coordinates and information that gives more context
+about its place. Node ids can be used as `origin` and `destination` when searching for itineraries for users.
+
+## The node object
+
+### Attributes
-```ruby
-require 'kittn'
+| Name | Type | Description |
+|-----------------------|----------|--------------------------------------------------------|
+| id | `int` | The id of the node. |
+| name | `str` | A human readable name that can be displayed to users. |
+| coordinates | `object` | Coordinates. Can be used to display the node on a map. |
+| coordinates.longitude | `float` | The longitude of the node. |
+| coordinates.latitude | `float` | The latitude of the node. |
-api = Kittn::APIClient.authorize!('meowmeowmeow')
-api.kittens.get
+> Json representation of an object:
+
+```json
+{
+ "id": 42,
+ "name": "Place de la mairie",
+ "coordinates": {
+ "longitude": 2.466311814729767,
+ "latitude": 49.192376994101174
+ }
+}
```
+## Search among nodes
+
```shell
-curl "http://example.com/api/nodes/search" \
+curl "http://example.com/api/nodes/search?value=place" \
-H "Authorization: secret"
```
@@ -96,16 +134,18 @@ curl "http://example.com/api/nodes/search" \
"count": 1,
"next": "http://example.com",
"previous": "http://example.com",
- "results": [{
- "id": 42,
- "name": "Place de la mairie",
+ "results": [{
+ "id": 42,
+ "name": "Place de la mairie",
+ "coordinates": {
"longitude": 2.466311814729767,
"latitude": 49.192376994101174
- }]
+ }
+ }]
}
```
-This endpoint allows to search among all nodes.
+This endpoint allows searching among all nodes.
### HTTP Request
@@ -113,20 +153,85 @@ This endpoint allows to search among all nodes.
### URL Parameters
-Parameter | Description
---------- | -----------
-value | Optional. If given, filter against node's names.
+| Parameter | Description |
+|-----------|--------------------------------------------------|
+| value | Optional. If given, filter against node's names. |
+
+# Itineraries
+
+The itinerary API allows you to search for itineraries for one or more passengers, to display propositions to them and
+to validate a given proposition.
+
+## The passenger object
+
+Describe a passenger for an [itinerary](#the-itinerary-object). A single passenger can book a trip for one or more
+person and this object has to be used to communicate the specificities of each passenger to Padam (as an example, if
+the passenger has a wheelchair, we have to know it in order to be able to make the best propositions to it).
-