|
|
The API uses some concepts that are really different from the web interface because the context is not the same at all. This page will give you some clues about those differences and how to use them to develop the API (add a URL, modify a behavior, ...).
|
|
|
|
|
|
Of course, the best would still be to go trough [DRF's tutorial and the API reference](https://www.django-rest-framework.org/) but the learning curve is quite steep, so for simple actions on the API, this page might be enough. Also it might be a good idea to read the [API raw usage wiki page](API/Raw usage) to get an idea of what's currently possible.
|
|
|
Of course, the best would still be to go trough [Django Rest Framework (DRF)'s tutorial and the API reference](https://www.django-rest-framework.org/) but the learning curve is quite steep, so for simple actions on the API, this page might be enough. Also it might be a good idea to read the [API raw usage wiki page](API/Raw usage) to get an idea of what's currently possible.
|
|
|
|
|
|
|
|
|
# The ACL "can_use_api"
|
... | ... | @@ -18,6 +18,8 @@ api.acl.can_view(user) |
|
|
|
|
|
# The URLs and routers
|
|
|
|
|
|
[Official DRF documentation about routers](https://www.django-rest-framework.org/api-guide/routers/)
|
|
|
|
|
|
The URL system mainly works the same way as for any other app: a path or regular expression associated with a view (and some namespacing options) are provided in a `urlpatterns` variable.
|
|
|
|
|
|
The difference lies in the use of a "router" to build most of those urlpatterns. A router is an object that automatically register [viewsets](#the-viewsets) and generates urls based on it. It also builds a root page that presents all the registered urls in a nice way.
|
... | ... | @@ -42,6 +44,8 @@ users-details |
|
|
|
|
|
## The class-based views
|
|
|
|
|
|
[Official DRF documentation about views](https://www.django-rest-framework.org/api-guide/views/)
|
|
|
|
|
|
The views even they could be managed by standard views defined as functions, it is highly advised to use class-based views instead because it means you can use pre-defined DRF's views objects as a base and not care about multiple points that are automated as soon as your view is subclassing `rest_framework.views.APIView` or one of its subclass:
|
|
|
* The `view.as_view()` method provides a view adapted for the API (CSRF exempted, ...)
|
|
|
* The handling of [authentication](the-authentication-classes), HTTP methods authorized and [permissions](the-permission-classes) are automatically done under the hood and the code left is smaller and simpler to understand.
|
... | ... | @@ -75,6 +79,8 @@ view = MyView.as_view() |
|
|
|
|
|
## The generics
|
|
|
|
|
|
[Official DRF documentation about Generics](https://www.django-rest-framework.org/api-guide/generic-views/)
|
|
|
|
|
|
In the context of mixing Django and the API, it is frequent to want to expose a queryset or an object via the API. To simplify the code of such action, DRF provides generic views defined in `rest_framework.generics`. Those generics are simply class-based views that creates generic `delete`, `get`, `patch`, `post`, `put` methods only based on a given queryset or an object. Here is the default behavior for each HTTP methods
|
|
|
|
|
|
| Method | Queryset-based behavior | Object-based behavior |
|
... | ... | @@ -137,6 +143,8 @@ view = MyGeneric.as_view() |
|
|
|
|
|
## The viewsets
|
|
|
|
|
|
[Official DRF documentation about viewsets](https://www.django-rest-framework.org/api-guide/viewsets/)
|
|
|
|
|
|
To go even further in the automation of exposing Django's model, DRF uses viewsets. The goal of a standard Django's viewset is to group similar view together to make the code more understandable while avoiding duplication of code. In the context of API, a very common use of viewsets is to expose a model by providing one URL to act on the whole queryset (list and create objects) and another URL to act on each of the objects (details, edit, delete). Do automate that DRF provides sone viewsets that handles nearly everything by grouping some pre-defined generics together:
|
|
|
|
|
|
* **ModelViewSet**: Exposes a Django's model by providing two URL:
|
... | ... | |