REST API

Overview

API root is located at /api/

Will return the API Root with links to the other endpoints of the api.

How to use

As of right now everything is in development

Planned features

Endpoints

Are easy to change the name of.

Sprint 1

• POST road network: /api/roadnetwork/
• POST production data (maintenance data?): /api/productiondata/ (/api/maintenancedata/)

Need to decide if the above endpoint should accept GET requests as well.

Need to look into how to accept bulks of data.

Later

• Retrieve road status for a given geographic area. How long since last time the road stretch was maintained and how much snow since last maintenance etc. (To be used for showing status on map.)
• Retrieve a road segment.

How to

Put api root at /api/

In backend/urls.py include your api app's urls.py file.

urlpatterns = [
    url(r'^', include('api.urls')),
    ...
]

This should be near the top of urlpatterns, because it is prioritized by order.

In your api/urls.py file, the urlpatterns router include should be set to api/

urlpatterns = [
    url(r'api/', include(router.urls))
]

Short explanations (and possibly some tip and tricks)

See the Django and Django Rest Framework documentation for more informantion

Urls

api/urls.py is the file where the api is routed. In the file there is a section where the router is declared and the different viewsets are registered and a urlpatterns variable that just places the api router on /api/. In the routing section, to add a new endpoint, just add new line with router.register(r'<endpoint>', <viewset>)

If is replaced with users, /api/users will be the endpoint for the viewset.

Views (viewsets)

Using a ModelViewSet list, create, retrieve, update and destroy actions are provided and do need to be declared, but can be overridden. There are others like ReadOnlyModelViewSet (pretty self explanatory what it does).

Queryset

The queryset variable is what set of data from the database to use with the serializer. In case of a basic viewset for a database model set it to queryset = <modelname>.objects.all().

We may have to use other, more complex queries for some of the functionality.

Serializer class

Selects which serializer to use for serializing and deserializing the data from/to the database. See the Serializer section for more information.

Permission classes

Some viewsets, like ReadOnlyModelViewSet have inbuilt permissions.

You can set your own permissions by doing this:

permission_classes = (permissions.IsAuthenticatedOrReadOnly,)

permission_classes takes a tuple. IsAuthenticatedOrReadOnly is a built in permission class and there are a few others, but you can make your own permission classes. (See below)

Custom permissions

Make an api/permissions.py file.

Example:

from rest_framework import permissions


class IsAdminOrReadOnly(permissions.BasePermission):
    """
    Custom permission to only allow admins to create and edit.
    Read only for normal users and unauthorized users.
    """
    def has_permission(self, request, view):
        if request.method in permissions.SAFE_METHODS:
            return True
        else:
            return request.user.is_staff

Description of class in docstring.

Checks if user is flagged as is_staff.

The permissions.SAFE_METHODS is a tuple containing the request methods GET, OPTIONS and HEAD.

Serializers

A serializer allow complex data such as model instances to be converted to native Python data types that can be rendered into html or json. It also provide deserialization, allowing data to be converted back to complex data.

HyperlinkedModelSerializer

A HyperlinkedModelSerializer is a ModelSerializer that generates a url for each row in a database table. Say you are making a serializer for the built in User model. If you use a HyperlinkedModelSerializer add a 'url' field to the fields metaoption and do a GET request to the api user endpoint. It will list all the users and also give a url to each specific user that can used for another GET request.

The Meta class

The Meta class has many different options that can be set.

Model

The model option specifies which model this serializer uses (database model). model = User

Fields

The fields option selects which fields from the model the serializer uses when serializing/deserializing. fields = ('id', 'username')

Models

Meta class

Similar to serializers the models supports metadata.

Abstract

The abstract option sets the model to be abstract. This can be used to make a template model with base fields if you want several of your models to have some of the same fields.

Example:

class BaseModel(models.Model):
    id = models.AutoField(primary_key=True)
    created = models.DateTimeField(auto_now_add=True)
    updated = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True

Usage:

class ProductionData(BaseModel):

This will include the three fields of BaseModel in ProductionData. The id field is the primary key and will auto increment. It will (should) also make it so the created field is set to the date at which the row was created and the updated field should be set to the current datetime every time the row is updated. Fields with auto_now_add=True and auto_now=True also have editable=False by default