API v2

Explore

API v2

Justification

The goal of this refactor is to have a clean and lean API that can then share with the public and third-parties.

This change should also enable us switch between different python frameworks and also move to microservices where/when the need be.

Description

0. Framework

We would be sticking with

django rest framework⁠

due to its stability and its robust permission management features.

1. Basic folder structure

⁠

⁠

To ensure that we still have the current API working whilst developing v2, we’d create a v2 sub folder - in each app - where most of the work would be done. The models.py file would maintain its current location in the app’s package.

Views would be a module that would contain different view files for each package. e.g for the fund app, there’s are a lot of views so we’d break them down in such a way that we can have similar views in a file. Then in the __init__py file of the views module, we import all views. For smaller apps e.g badges We can have just a single

views.py⁠

file.

We would be making use of viewsets with list and detail routes as opposed to APIView. This would help to generate the documentation via

core-api⁠

would be explained later.

from rest_framework import viewsets

class UserViewSet(viewsets.ViewSet):

def create(self, request, **kwargs):

pass

def update(self, request, pk=None, **kwargs):

pass

def retrieve(self, request, pk=None, **kwargs):

pass

def list(self, request, **kwargs):

pass

def destroy(self, request, pk=None, **kwargs):

pass

@detail_route(methods=["GET"])

def register_2fa(self, request, **kwargs):

pass

@list_route(methods=["GET"])

def activate_user(self, request, **kwargs):

pass

Tests would be in their own package where we can have unit tests (services, models) and integration tests (views)

There would be a Service class in

services.py⁠

file which would contain code that bridges view-model interaction so the view does not interact with the models directly but via the service class. For example,

in plans/services.py there would exist a PlanService class . When a call is made to the create plan endpioint, we pass the data to the PlanService to create the plan and then get a response. i.e

from

plans.services⁠

import PlanService

from rest_framework import viewsets

class PlanViewSet(viewsets.ViewSet):

def create(self, request, **kwargs):

"""

code ommited for brevity

"""

plans_service = PlanService(**args)

result = plan_service.create_plan(**args)

.....

If the PlanService has to interact with models from the card app, it would be done via the CardService *(We may need to consider using DI here)

Serializers.py would contain the serializers of the models in their respective app. The serializers would handle validation for things like data type checking, text length check etc. We can have a number of serializers per model. e.g we can have a UserSerializer for update and retrieve and a UserCreationSerializer for create.

Tasks.py would contain app specific background tasks (via celery)

Urls.py would contain the router for the package. We would then import the router url in the project level router.py.

Utils.py would contain specific functions that are re-used in the app services. We would rarely have to create this file as most of the work would be done by the Services already. We would most likely use the project level utils file for shared utility code used in multiple services.

2. Documentation.*

Another advantage of using Django Rest Framework is the vast amount of libraries one has available to work with.

⁠

Coreapi⁠

. Core API allows us to create a documentation page for our APIs that frontend developers can easily interact with. Here is an example of what it looks like -

https://medium.com/@madtab/creating-an-api-with-django-rest-framework-part-3-documentation-3b2fe3445e10⁠

⁠

It requires little configuration as drf is able to read metadata from serializers and use the model structure create the documentation. It is also customizable.

3. Permissions.

We would be handling permission with DRF’s default permission handler. We’d create custom permission classes for different types of users, we would also be considering creating permissions on an app basis e.g

ReadPlanPermission,ReadCardPermission,UpdatePlanPermission , etc

Assumptions

Everyone on the team understands DRF

We would be working with the documentation created on

readme.io⁠

⁠

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.