Reasons why Python's Dictionary is considered the best choice for forming scalable REST API responses

REST API Development is bound to some rules that we developers do not follow most of the time either because of lack of knowledge, no guidance or hurried development without discussion and many others.

#restapi #scalable #response #json #python #django #api

Let me start this post with a small story of mine. It's been almost 6.5 years since I heard about Python's dictionary in 2016. The very first time, I learned Python programming because I was looking for a job at that time (The thing is, I had gotten an Interview call for a Python opening so somehow I prepared & got ready for the Interview in a mini Startup company).

As I knew, the age of IT companies was the age of Angular JS, Node JS, Python/Django, etc. People used to talk about creating webpages, developing APIs, etc. most of the time.

Somehow the Interview ended up with 2-3 coding Questions on White paper followed by executing the written code on a Desktop. The questions were simple.

On the first day only, I got a task to practice and learn GIT on Codecademy in 6 hours. It was sufficient time given & in this way the first day was over.

And the second day onwards, I got a different task of learning Django & its basics with simple forms submissions, etc. Slowly slowly the new company started giving me tasks for APIs development without using the Django REST framework followed by how to call & consume them using pure JavaScript (no jQuery) and taking the required actions on Frontend.

Slowly slowly I started learning about Backend APIs development + Frontend integration. Most of the tech stacks that I was preferring that time were

1. Python2.7/Django1.8, Python3.2/Django1.9 etc.
2. HTML5
3. CSS3 (Bootstrap3 as CSS framework)
4. JavaScript (Later I started using jQuery as well)

After completing 1 year in the Organisation, I was given a task to develop a Responsive Web Application to book Cabs with a Text messaging facility and I completed this within 15-20 days (QA was also involved). The client also visited our Organisation and the website was made live as https://surecabs.in/ but later after 6 months or a year (it was shut down, not sure about reasons etc).

Now Let's talk about the scalable API response!

Now let's finish the story here and start with the actual stuff I was gonna talk about!

I was always told to send 3 fields in the REST API responses. This response is scalable. And the fields are status, message, and data (Note that everything which is going to be used to display on the UI, etc. should go in the `data` field).

Here is the example API response I used to develop at that time.

I'd like to tell you why is this API response scalable! The answer is we can add additional data to it without changing the previous response so there's no need to work or bother about any changes to be done in the previous integrations & we can directly start working on new components/integrations.

Ex: Product managers decided to show organisation info along with the `users`, so in this case, Backend developer can just add one field named `organisation` with the required data as value in the previous response and that is it.

Now, let's talk about an unscalable API response!

Here is an example REST API response that can't be scaled if we think about making sure to retain the 3 fields i.e. status, message, and data.

Now, if you were asked to add the Organisation details as well as we saw before, here in this case it is not possible to add under the `data` field (because that is an array/list).

So without introducing the 3rd field, it is not possible to add Organisation details (but this will break the rule of having 3 fields i.e. status, message, and data).

What I mean is the below response (An unscalable one under specific rules of API development, does not look good)!

Even this too, doesn't look good (Here I replaced `data` with `users` just to make it more readable but again we broke the rule of having 3 fields i.e. status, message, and data).

In the end, thank you very much for reading this article carefully! If you have any suggestions, you can drop your thoughts in the comment below. I would be happy to take a look and respond!

Thanks once again!