The django-sphinx-hosting REST API
django-sphinx-hosting
provides a REST API for interacting with the the application in
a programmatic way. The API is implemented using Django REST Framework.
See Configure Django REST Framework for instructions on how generally to
configure your settings.py
file to use DRF for our API.
How to reach the API
The API is reachable at the following path of your install: /api/v1/
. See
REST API for the description of all endpoints.
Authentication
It’s up to you to provide an authentication mechanism for the API via the
REST_FRAMEWORK
setting in your settings.py
file. django-sphinx-hosting
will use whatever you provide for the DEFAULT_AUTHENTICATION_CLASSES
setting.
See the Django REST Framework: Authentication for more information on how to configure authentication for DRF.
Example
Here’s an example of how to configure the API to use Token based authentication:
INSTALLED_APPS = [
...
'rest_framework.authtoken',
...
]
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': ('rest_framework.authentication.TokenAuthentication',),
# https://www.django-rest-framework.org/api-guide/parsers/#setting-the-parsers
'DEFAULT_PARSER_CLASSES': ('rest_framework.parsers.JSONParser',),
# https://django-filter.readthedocs.io/en/master/guide/rest_framework.html
'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',),
}
Note
We always need at least the DEFAULT_PARSER_CLASSES
setting and the
DEFAULT_FILTER_BACKENDS
listed above for the API to work at all, regardless
of the authentication mechanism you choose, so be sure to include them.
Then migrate the database to create the Token
model:
$ python manage.py migrate
And then create a token for your user:
$ python manage.py drf_create_token <username>
To use this token, you must provide it in the Authorization
header of your
requests. Example:
$ curl -X GET \\
-H 'Accept: application/json; indent=4' \\
-H 'Authorization: Token __THE_TOKEN__' \\
--insecure \\
--verbose \\
https://localhost/api/v1/projects/