... | ... | @@ -7,19 +7,19 @@ Of course, the API is not publicly exposed to everyone. Thus some mechanisms of |
|
|
*:warning: As a security warning: it is highly advised to use the API only with TLS/SSL activated. If not doing so, you are exposing your data to be leaked and/or your database to be vulnerable*
|
|
|
|
|
|
|
|
|
1. [Enable the API](#enable-the-api)
|
|
|
2. [Authentication](#authentication)
|
|
|
1. [Authentication by session cookie](#authentication-by-session-cookie)
|
|
|
2. [Authentication by token](#authentication-by-token)
|
|
|
3. [Permissions](#permissions)
|
|
|
1. [The API permission](#the-api-permission)
|
|
|
2. [Standard ACL](#standard-acl)
|
|
|
4. [Pagination](#pagination)
|
|
|
5. [HTTP status codes](#http-status-codes)
|
|
|
6. [RESTful status](#restful-status)
|
|
|
1. [Enable the API](#enable-the-api)
|
|
|
2. [Authentication](#authentication)
|
|
|
1. [Authentication by session cookie](#authentication-by-session-cookie)
|
|
|
2. [Authentication by token](#authentication-by-token)
|
|
|
3. [Permissions](#permissions)
|
|
|
1. [The API permission](#the-api-permission)
|
|
|
2. [Standard ACL](#standard-acl)
|
|
|
4. [Pagination](#pagination)
|
|
|
5. [HTTP status codes](#http-status-codes)
|
|
|
6. [RESTful status](#restful-status)
|
|
|
|
|
|
|
|
|
# Enable the API
|
|
|
# 1. Enable the API
|
|
|
|
|
|
The first step is to enable the API. Indeed the API is intended to be independent from the rest of Re2o, it is only an interface. The consequence is that it was meant to be an optional app and not a required app. Even though it is highly advised to activate it, you are free to deactivate it at any time without any direct consequences for Re2o (but the services using it might broke because the API endpoints will not be reachable any longer).
|
|
|
|
... | ... | @@ -38,21 +38,21 @@ $ python3 manage.py migrate |
|
|
After reloading the web server, you should now be able to access the API root page (`https://<hostname>/api/`)
|
|
|
|
|
|
|
|
|
# Authentication
|
|
|
# 2. Authentication
|
|
|
|
|
|
Except for the API root page (`https://<hostname>/api/`), all pages of the API need you to be authenticated in order to get any information. This behavior is mandatory as we can not expose personal or confidential data to anonymous user. First it may be needed to know who accessed it if needed and it is also needed to be authenticated so, the ACL can be checked to determine if you have the access to such data.
|
|
|
|
|
|
Two way of authenticating are available, even if in theory you can use both in all cases, they are meant to be preferred over the other in some circumstances. If you want to explore the API with your browser and your credentials, the recommended way is to use session cookie. On the contrary, if you want to use a script to access the API with a dedicated user's credentials, prefer the token-based authentication.
|
|
|
|
|
|
|
|
|
## Authentication by session cookie
|
|
|
## 2.1. Authentication by session cookie
|
|
|
|
|
|
This authentication method uses a cookie returned upon you connection to Re2o. Indeed it is the exact same session cookie used to navigate through the web interface (handled by django-auth). This means that once you log in the web interface as usual and your browser has saved the cookie, you will also be authenticated on the API interface since your browser will send this cookie automatically. This is why, this authentication method is the recommended way to use the API through a browser:
|
|
|
* Log in via the usual log in page (`https://<hostname>/login/`)
|
|
|
* Explore the API (`https://<hostname>/api/`)
|
|
|
|
|
|
|
|
|
## Authentication by token
|
|
|
## 2.2. Authentication by token
|
|
|
|
|
|
This authentication method is easier to use in an automated process but more complex by using a standard web browser. It requires you to add a `Authorization` field in the header of your request with a token given by the server. A token is specific to a user, so to get one, you will need to provide a user's credential but once you have a token, you no longer need the password, the token is your credential. For security concerns, tokens expire after 24 hours, meaning that even in case of a leaked token, it can be used only for at most 24 hours. After that delay, the server will require you to re-provide the credentials in order to renew the token.
|
|
|
|
... | ... | @@ -95,17 +95,17 @@ This authentication method is easier to use in an automated process but more com |
|
|
}
|
|
|
```
|
|
|
|
|
|
# Permissions
|
|
|
# 3. Permissions
|
|
|
|
|
|
Being authenticated will not do everything you will need also need to have the right to access the data you are asking for. Most of the endpoints requires you to have specific [ACL](User Documentation/ACL) to access them. For the exact list of ACL required, see the [endpoints' details page](API/Endpoints). In addition, you will need to have the *API Permission* to access any API page (except the API root page).
|
|
|
|
|
|
|
|
|
## The API permission
|
|
|
## 3.1. The API permission
|
|
|
|
|
|
Every user that wants to use the API (for any endpoint) need to be granted the *API Permission* labeled `api | api | can see the api` in the groups' rights list in Re2o's web interface. It is mandatory and intended by design. Even if, in theory and with a lot of effort, one (with the right ACL) could parse the HTML of the web interface and get the information requested without the *API Permission*, having this specific permission allow to quickly identify which user can access the API and easily restrict someone to non automated process.
|
|
|
|
|
|
|
|
|
## Standard ACL
|
|
|
## 3.2. Standard ACL
|
|
|
|
|
|
In addition to that permission, a user accessing an endpoint, will need specific ACL (depending on the models affected by the request and the method used) for the requests to be accepted. In general, the ACL required are the following but some exceptions exists and all endpoint do not fit in this general rule, check the [endpoints' details page](API/Endpoints) for more precise details.
|
|
|
|
... | ... | @@ -120,7 +120,7 @@ In addition to that permission, a user accessing an endpoint, will need specific |
|
|
| DELETE | not authorized | `can_delete` |
|
|
|
|
|
|
|
|
|
# Pagination
|
|
|
# 4. Pagination
|
|
|
|
|
|
By exploring the ACL one will probably figure out that the model-based endpoints (those reflecting the instances of a model) and some other endpoints are using a pagination system. The results are split in sub-lists and you need to query the next page for the next part of the results. This is to avoid accidentally requests that overload the server by asking it to dump thousands of database entry and to avoid responses of several MB because of a huge list returned.
|
|
|
|
... | ... | @@ -152,7 +152,7 @@ Two query parameters can be used to control the pagination: |
|
|
* If over-the-limit integer, the limit (10000) is selected
|
|
|
|
|
|
|
|
|
# HTTP status codes
|
|
|
# 5. HTTP status codes
|
|
|
|
|
|
Here is a complete list of the HTTP status code that can be returned while interacting with the API and their meanings. Of course, one can also encounter other HTTP status code due to errors independent from the API (e.g. 404 (*NOT FOUND*) or 503 (*SERVICE UNAVAILABLE*)):
|
|
|
|
... | ... | @@ -170,6 +170,6 @@ Here is a complete list of the HTTP status code that can be returned while inter |
|
|
* The resource requested is not accessible for this user
|
|
|
|
|
|
|
|
|
# RESTful status
|
|
|
# 6. RESTful status
|
|
|
|
|
|
This API is intended to be the RESTful possible, but it is not entirely. The only feature missing is the versioning of the API which highly help maintaining the compatibility with old services using the API. Unfortunately, versioning the API also means maintaining the exact same behavior of old endpoints, which is a complicated task in the context of Re2o where the models' definition change quite often and maintaining old endpoint that may not reflect the project anymore will mainly be a burden. Thus it was decided not to version the API at the risk of breaking some service compatibility. This risk is considered to be bearable in the current context were Re2o's instances are installed: the production installations are quite well-known and the teams managing it are highly available in case of a problem. |
|
|
\ No newline at end of file |