diff --git a/slate/source/includes/reference/_authentication.md b/slate/source/includes/reference/_authentication.md index 9e584e91..0eb91daf 100644 --- a/slate/source/includes/reference/_authentication.md +++ b/slate/source/includes/reference/_authentication.md @@ -2,6 +2,8 @@ ## Authentication +### Authentication Basics + > Get authentication token: ```bash @@ -42,6 +44,13 @@ Header | ------ | Authorization: JWT `your_token` | -The token expires after a set amount of time. The expiration time is dependent on WebODM's settings. You will need to request another token when a token expires. +The token expires after a set amount of time. See [Token Expiration](#token-expiration) for more information. Since applications sometimes do not allow headers to be modified, you can also authenticate by appending the `jwt` querystring parameter to a protected URL. This is less secure, so pass the token via header if possible. + + +### Token Expiration + +The token expires after a set amount of time. The expiration time is dependent on WebODM's settings. You will need to request another token when a token expires. + +You know that a token has expired if any call to an API returns a `403` status code with the JSON body `{'detail': 'Signature has expired.'}`. diff --git a/slate/source/includes/reference/_handlingerrors.md b/slate/source/includes/reference/_handlingerrors.md new file mode 100644 index 00000000..53763825 --- /dev/null +++ b/slate/source/includes/reference/_handlingerrors.md @@ -0,0 +1,16 @@ +## Handling Errors + +All API calls use the status codes as described in the [Django REST Framework's Status Code Guide](http://www.django-rest-framework.org/api-guide/status-codes/), but generally you only need to check for success status code (status code `200` or `204`) and handle the special case of [Token Expiration](#token-expiration) (status code `403`) and report an error otherwise. + +### Error Status Codes + +This is not an exhaustive list, but common error codes are listed below. + +Status Code | Description +----------- | ----------- +401 | Unauthenticated +403 | Forbidden (token expired?) +400 | Malformed request +404 | Not found + +For security reasons, sometimes an operation which should return `403` returns `404` to avoid disclosing IDs and other information from attackers. diff --git a/slate/source/includes/reference/_project.md b/slate/source/includes/reference/_project.md index 0656f197..93bf8c3a 100644 --- a/slate/source/includes/reference/_project.md +++ b/slate/source/includes/reference/_project.md @@ -57,6 +57,9 @@ Parameters are the same as above. Upon deletion, all [Task](#task) items associated with the [Project](#project) are deleted also. The operation is irreversible. +### Get single project + +`GET /api/projects/{id}/` ### Get list of projects diff --git a/slate/source/index.html.md b/slate/source/index.html.md index bea8b259..8fc56208 100644 --- a/slate/source/index.html.md +++ b/slate/source/index.html.md @@ -19,6 +19,7 @@ includes: - reference/task - reference/processingnode - reference/permissions + - reference/handlingerrors - fordevelopers ---