Relationships and its usage in Open Event Orga Server

JSON API is a specification for writing RESTFul APIs (CRUD interfaces). This specification basically sets the standard for a client to request the resources and how a server is supposed to response minimizing the redundancy and number of requests.

If we look at the general implementation of RESTful APIs, we see that we are working on creating every endpoint manually, there are no relations. Sometimes different endpoints are being created for some slightly different business logic than other. We solve this purpose specifically the relationships using JSON API spec.

Features of JSON API

Apart from CRUD interface, JSON-API-Spec provides

  • Fetching Resources
  • Fetching Relationships
  • Inclusion of Related Resources
  • Sparse Fieldsets
  • Sorting
  • Pagination
  • Filtering

For Open Event API Server we need these below

  • Proper relationship definitions
  • Sorting
  • Filtering
  • Pagination

So JSON-API spec is a good choice for us at Orga Server since it solves our every basic need.

Overview of Changes

Firstly the main task was shifting to the library flask-rest-jsonapi because this library stands to our four needs in API. The changes included:

  • ensuring JSON-API spec in our requests and responses (although the most of the work is done by the library)
  • Reusing the current implementation of JWT authorization.
  • To locate the new API to /v1. Since Orga server is going to be API server with Open Event system following the API-centric approach, therefore, there is no need to have /api/v1
  • Now out timestamps in response and request will be timezone aware thus following ISO 8601 with timezone information (Eg. 2017-05-22T09:12:44+00:00)

Media type to use: application/vnd.api+json

A Relationship in JSON API

To begin with APIs, I started working on Sessions API of Orga server and the relation of a session with the event was represented as one of the attribute of Schema of the Session API like this below,

event = Relationship(attribute='event',
                        self_view='v1.session_event',
                        self_view_kwargs={'id': '<id>'},
                        related_view='v1.event_detail',
                        related_view_kwargs={'session_id': '<id>'},
                        schema='EventSchema',
                        type_='event')


  • attribute: name of the attribute with which this will be referenced in response API
  • self_view: A view name which represents the view of this relationship. This is a relationship endpoint of sessions API.
  • self_view_kwargs: view_kwargs for self_view, this is used to provide ID of the specific record to the relationship endpoint.
  • related_view: An endpoints to the related API/Object. Here the related object is ‘event’ so I have provided the endpoint to get the event detail.
  • related_view_kwargs: Here we can provide kwargs to the related object’s endpoint. Here we are sending the value of <Session_id> URL parameter on the related endpoint by mapping it with “id” of the current session object.
  • Schema: this is the schema of the related object. Since we have related object is event, therefore, added EventSchema of it.
  • type_: this is the type of related object which is event here.

After defining them, the magic here is no need to define and inject the relationship endpoints in the responses. We just need to add one route to v1.event_detail and we have relationship ready.

To make this work, I added these on routes file:

  • ‘/sessions/<int:session_id>/event’ to the v1.event_detail
  • api.route(SessionRelationship, ‘session_event’,
             ‘/sessions/<int:id>/relationships/event’)

And we have Relationship ready as Session -> Event in the API ready. We can use these relationships to Get the relationship Object(s), Updated them or Delete them. This helps Orga Server is a very efficient scale since many of our endpoints are related with events directly so instead of separately defining relationships we are able to do this with the help of JSON API and flask-rest-jsonapi

An Example Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "relationships": {
      "event": {
        "links": {
          "self": "/v1/speakers-calls/3/relationships/event",
          "related": "/v1/speakers-calls/3/event"
        }
      }
    },
    "attributes": {
      "announcement": "Google",
      "ends-at": "2023-05-30T09:30:10+00:00",
      "hash": null,
      "starts-at": "2022-05-30T09:30:10+00:00",
      "privacy": "public"
    },
    "type": "speakers-call",
    "id": "3",
    "links": {
      "self": "/v1/speakers-calls/3"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "/v1/speakers-calls/3"
  }
}

Above example shows the relationships in the response object. We can directly check in the application using these APIs that to which type of objects this object is related with and endpoints to get related data.

Next steps in the implementation are Docs for APIs, permissions implementations to secure the endpoints and setting up unit testing of the endpoints which will be discussed in next posts.