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 :ref:`configure-django-rest-framework` for instructions on how generally to
configure your settings.py
file to use DRF for our API.
The API is reachable at the following path of your install: /api/v1/
. See
:doc:`/api/rest_api` for the description of all endpoints.
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.
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/
The API endpoints all require that the user be authenticated. All users have read-only access to all API endpoints, but for write access, they must be in the appropriate group or groups from :doc:`/overview/authorization`.