DEV Community: Santosh Bhandari

Proper API Response structure {} - Importance & Advantages!

Santosh Bhandari — Wed, 01 Jun 2022 13:23:19 +0000

ℹ️ Before starting to write anything I would like to mention that all this is my personal thoughts based on my knowledge, experiences and issues I have faced in the past. ℹ️

It is the modern age of Internet, and there are thousands if not millions of website we have stumbled upon. Hundreds of which may be dynamic (i.e. fetch data whenever we request from some data source.)

The whole process of data fetching in most of the cases is done through API (SOAP, REST or GraphQL).
Thus you can consider an API as the translator between two people who talk two different language. Just imagine what would happen if the translator translates it wrong.

Things to Consider

Communication is key!

Thus, there are lots of things which I think we should consider when setting up API response.

Do not use top level data Objects or Arrays

I used to think it's easy to just send the data after fetching it directly from the Database.

For e.g. sending this response for API call https://api.xyz.com/users/1

{
  "fullName": "Full Name",
  "dateOfBirth": "2000-01-01"
}

Or the e.g. below for API call https://api.xyz.com/users

[
  {
    "fullName": "First User",
    "dateOfBirth": "2000-01-01"
  },
  {
    "fullName": "Second User",
    "dateOfBirth": "1990-04-04"
  }
]

While it will be easy to return the data like this, it will cause a huge problem sooner or later.

The major problem being We can't add extra information in the first response object, and it's not even possible in the second response array.

Use consistent variable name casing

There are variable ways to name a variable:

camelCase being the popular one around JavaScript developers.
snake_case being the popular one around Python developers (snake_case for Python developers... what a coincedence...).
PascalCase
kebab-case

I think it was not really necessary to mention about it, because developers using a specific language already have their own preference over variable name casing.

Just a note from my side; using multiple name casing in a single project is a big NO!

If possible, I would even suggest everyone to grab a name casing technique and follow it throughout the entire journey of programming in life.

Use proper variable names

This is not just for the API response object, but also the codes itself and Database entity itself as well.

I am pretty sure there are thousands of articles/notes metioning about how variable names should be written so I am not gonna go in depth, but I would like to attach a simple yet important note about this topic:

Variables name should be "As short as possible, as long as required"!

Solution

The simple yet powerful solution to API response structure is to simply have the data structure as follow:

For e.g. sending this response for API call https://api.xyz.com/users/1

{
  "message": "Successfully fetched User data",
  "data": {
    "fullName": "Full Name",
    "dateOfBirth": "2000-01-01"
  }
}

Or the e.g. below for API call https://api.xyz.com/users

{
  "message": "Successfully fetch Users data",
  "pagination": {
    "page": 1,
    "count": 2,
    "perPage": 10
  },
  "data": [
    {
      "fullName": "First User",
      "dateOfBirth": "2000-01-01"
    },
    {
      "fullName": "Second User",
      "dateOfBirth": "1990-04-04"
    }
  ]
}

You might have already noticed that I am able to send message in the API response. And also in the second API usage example, I am even able to send pagination details.

There will be thousands of data processing happening, so pagination is obviously to be done sooner or later. However in the previous approach we could not properly mention about the pagination details. Which we have overcome.

You might now be wondering, Isn't it painful to access the data going one more level deep in the object? i.e. response.data instead of response.

The answer is Yes, but apart from that downside, it's only good point I can think up of.

For e.g. lets say we have to respond with error message if the API request is invalid. Following this approach, we can simply send the response like:

{
  "message": "Invalid email address" // or any other error message
}

And now in the frontend/mobile app, we can always refer to response.message to get the information about the API usage. And to understand if the API call was a success or failure, we can use HTTP status code of the API call.

The main point

The major point of all this discussion is that the APi response should never be a top level data object itself.

Instead use an object which contains all the information you want ot share from server to frontend (not related to API).

And within the top level object, include the data related to the API call inside a result or data key.

This will result in clean and consistent API response acorss every API endpoint. And also you will be able to share extra information which is not related to the specific API call.

Conclusion

I have done this mistake in the past and learnt a hard way from it. That doesn't mean you have to make this mistake yourself to learn.

You can try implementing this approach I have mentioned in your next project (or even your current project if possible without major breaking changes).

If you are someone developing API, I would love to hear your thoughts about this approach and if you would like to switch to this approach (if not already using).

If you are someone who consumes API, I would love to hear your thoughts about how this change (if it is not what your current API provides) would affect you.

If you are already using this approach, then cheers, you are making life of yourself and the frontend developer easy 😉

API Party: Working with APIs!

Santosh Bhandari — Fri, 06 Nov 2020 11:54:08 +0000

👋 Hello everyone, I hope everyone is doing fine!

I have been using Vue & Nuxt for a while now to develop various webapps. Most of mine works are personal or hobby projects.

For the past 3-4 days I have been working on a new project. API Party!!

Github link to the project is available at the bottom!

You can check the project live here: https://apiparty.vercel.app

What is it?

API party is yet another project to list hundreds and thousands of awesome API that are being used all around the world.

Why another project then?

Earlier I was working on a project but due to some error I got bored with it. After that I checked my to-do list which has stuffs from years back. Then I saw this project idea which I had noted when I didn't even know web dev. So then I instantly started working on it.

Also I found it can be useful for many users to find just the API they are looking for.

What are the features?

As I already said the entire project is done within 3-4 days of time period with around ~3:45 mins of work (includes today's work time as well). Because of that there are really few features. But still here is the list:

Open Source
Categorized list
Filters (search only as of now Will expand for sure)
Nice UI (I would love to know if you like it or not 😉)
Miscs information about the API
- HTTPS support
- Authentication type
Documentation/API links
And much more to come...

Future Plans

Here are some of the ideas that I have in my mind. Hopefully they will land soon on the production!

Add more filters (Based on the misc. details)
Add articles letting users know about API, usage and more
Move to a dedicated domain
And much more to come...

Open to contributions

As of now I am the only one working on this project and I have shared this to limited number of users that I know. You guys can use/share it with your friends and community members so that they can know about it and hopefully the project can benefit the user in any way possible.

But for the project to be beneficial it has to contain good amount of resources that are helpful right ??
The project has few resources (API details) as of now. So you can contribute to the project.

Let's make it By the PEOPLE, to the PEOPLE, for the PEOPLE!

Post Hacktoberfest

It hasn't been even a week since the end of Hacktoberfest 2020. The question is Are you still contributing to open source??

If you had been looking to contribute but were unable to find what and where to do, then you can contribute to this specific project.

You can contribute to this project by:

Submitting bug reports/ideas to improve the project
Adding new API to the list
Engaging with the community
Sharing the project with other people

All these stated above and many more are the ways to contribute to open-source projects. And I would be happy to see any sort of contributions 😄

bsantosh909 / api-party

Awesome list of amazing API to be used!

If you read all the way upto here then I really appreciate it. Leave your thoughts about the project in the comments below. ✌️

#StaySafe #KeepDeveloping #BeHappy

Adding commenting system to website!

Santosh Bhandari — Thu, 11 Jun 2020 13:32:51 +0000

This article was originally posted on my blog here!

The blog article over at my site contains few other alternatives that are not listed below!

Also I am open for any sort of feedbacks ❤️

A community or website can operate better if users can engage more over it. If your website already doesn't have the commenting system then you are missing a lot from your users. Users prefer to be over the website where one can engage actively i.e. discuss, comments, react to the articles/content etc. Don't you prefer the same way?

If you also prefer having users on your website engaged then you have made a wise decision being here. Today I am going to talk about the user engagements in any website in general.

Introduction

Users, including me, would love to have any sort of engagement method when visiting a website. I prefer to talk actively with other users and discussion about various topics. If I find website which doesn't allow me to comment for any article published there, then most likely I won't visit the website again. Talking from the perspective of website developer it is a huge loss. So better not delay a moment to implement the commenting system in your website/blog if you know how to do it. But if you are not aware where and how to start then proceede through the article till the end. After that you will be able to implement comments in your website with no problem at all!

Implementation

If you are a big company or a big project with dedicated resources and members then implementing comments in your website won't be hard at all. But what if you are a solo developer or a small team with limited resources? Things can be really tough right? Yeah it can be, but do not fear. I have you covered this time!

I took a day out of my life and invested it all to help everyone out there just like me; just like me who wanted to implement comments system in their website but were in a hard spot with no knowledge about where to start. I have made a small list with every necessary details possible so that you won't have to wonder anywhere else to start with adding comments to your site.

These commenting plugins below are what I found by searching around the internet. There may be many more out there, but after knowing about these you won't have to wonder anywhere else. So let have a look at them:

Disqus

Disqus is the most popular commenting system that lots of websites use. Its amazing features and ease of use makes it the most popular choice amazing many users and developers. It comes with really amazing features, so lets have a look at them:

FREE
Supports devices from desktop to mobile, including Google AMP
Supports 70 languages and counting
Real time comments
Reactions
Automatically adapts to your site's design and colors or you can set it to your own liking
Allows users to comment with rich media i.e. picture, gifs and videos
Complete moderation options
Automated spam moderation
Notifications
Content recirculation
Subscriptions
Analytics
And many more...

Sorry if I went for only listing the features. Because if I had to describe them all then this article would get super long. So I though to keep and short and meaningful.
If you want to have a detailed information about all the feature you can head to the official disqus site and get detailed information about anything you want to know.

Although I would love to mention that disqus is FREE. But you do have the options to update to a paid version with addition features on the line. It's completely your choice if you want to upgrade or not. But if you are a solo developer or small team then I would suggest to work with the free version. Because It is REALLY AWESOME even when used as free.

Even my site has various blog articles with disqus comments plugin installed. Which means if you are reading this article on my site then you can let me know in the comments below. If not head over to this article originally posted on my site and let me know I love when people interact with me!

Facebook

Facebook is a really well known global brand. Even if you don't user it you might have heard about it once in your lifetime. That already explains how famous it is. There are millions of people using facebook and that is one of the reason why facebook launched it's own commenting system.

If your website is focused upon user base from facebook or if your site is related to facebook by any means then you should go for this system. If not I would suggest not to add extra pain in your life. Wonder why? Lets get to the feature and you will know by yourself!

FREE
Can be used with users registered on facebook only. That's why not good for site targetting audience outside of facebook!
Facebook life feel. It is exactly as what you would see in the platform itself, so gives the home like feeling to the users!
Admin panel for all moderation and related stuffs
Webhooks
And many more...

Although facebook itself is really well known global brand, the commenting system provided by it is not good outside the scope of fecebook realted stuffs. So better realize and think about it if you are planning to use it on your site already!

Spot.IM

Spot.IM is a really new thing for me as well. I had never heard about it till date. Thanks to you guys I learned something new But after looking at it the only thing I can say is WOW. It looks really promising because of all the features it has, but I could not find any details about it's pricing so you guys got some task to do if you plan to use it! Lets dive into it's features:

Conversations; yeah thats simply commenting system but with really rich detailings though!
Community spotlight
Live blogs; to give real time updates to your users for anything critical, important or emergency
Reactions
Powerful moderation options with AI integrations
User profiles and notifications
Analytics and insight
And many more...

All these features look really promising for sure. I am already thinking of doing a small project to test it out with amazing people like you. If you are eager just like me or if you already use it then let me know in the comments below.

HTML Comment Box

HTML Comment Box is simple yet powerful commenting system. There is nothing much to describe about it because it is just plug-and-play stuff. But if you have a look at the site you will see additional widgets available. Those are really awesome. So make sure to have look at them!

Viafoura

Viafoura is another of those promising looking commenting system I found while working on this article. Lets dig right into its features:

Real time conversations Includes rich features display
Live stories for live streams
Community chat
Automated moderation
Moderation possibilities
Community reviews
Integrated login
User personlization
And many more...

It is yet another of that amazing stuff which I want to try out someday.. Let me know in the comments below if you are impatient just like me to test it out!

Closing notes

It was a really fun time writing article. And I learnt something new today about all the posibilities of commenting system. I did realize that disqus or facebook is not the only stuff that is taking the market. There are really awesome stuffs, maybe even better than those existing that is still unknown to many people just like me.

As I discussed in the entire article Let me know about all your thoughts and feedbacks about this article. I will be hearing them all and hopefully you will teach me something new as well.

Until next time, farewell, Stay Safe!

What keeps you motivated ??

Santosh Bhandari — Sun, 07 Jun 2020 12:29:01 +0000

Over 6 years of programming knowledge
tranformed form complete noob to not a noob anymore
20+ projects started (double or triple the count if rewrites are allowed)
But the end result, No successful project till date!

The journey of over 6 years of programming has really been fun. I learnt so so so many new stuffs and improved myself a lot. But when I look back at the successful achievements of mine, I see nothing to be shown.

I really am proud of what I have learnt, but there definitely is something missing because of which there is no actual outcome. I never have reached the completion stage for any project because I get demotivated by various factors. But the cycle goes on I do get back to them and make minor progress, and leave it back again.

I really would love to know what keeps you guys motivated, maybe I can learn something from you guys that will keep me motivated as well ??

Sharing experiences is the best way to help other grow ❤️

Creating Markdown powered blog with nuxt

Santosh Bhandari — Sun, 07 Jun 2020 10:31:47 +0000

Creating blog is a passion of lots of people; that includes me. But starting out with it is really really hard. So I thought to share an easy way (If you are familiar with Vue) to create own blog. Technically there are various methods of doing this. But of the most impressive and famous way is Jamstack and the entire article is based upon it.

About Jamstack

So if you are already wondering what is jamstack and why jamstack, then you should head over to the jamstack website to know more about it. Because if I started talking about it, the article can get really long 😜. Altough the below listed are very basic ones but here are some awesome feature you should know:

No need of server to host website
Higher security
Cheaper

With that being said, JAMstack makes things only better!

Prerequisites

To get started with buliding your own blog we need to install few things. You need to have Node.js installed on your machine!

Nuxt

It is the most essential stuff today. It is really easy if you know vue. Also it provides way more than just generating static sites. This is just one of its awesome features. With it you can try so many awesome things and it even makes so many complex stuffs really really easy. It also has an active community and really helpful developers and core team members. To know more about it you can have a look at the official website!

Nuxt content

Nuxt content is an official module by the nuxt team which aims to provide ease to use features while working with markdown, JSON, YAML and _CSV files. Although it is a preety nuch module by the nuxt team, it already contains really amazing feature which makes our task easier. Also the dev team is working to add new features to the module. So you should keep track of the module to learn about the new amazing features that the module will be getting. More information about it can be found here!

Thats basically what we will need to start developing the blog. So lets dive deep into building the blog!

Development

There are few phases of developing the blog. I will try to explain them with minimum words but with maximum meaning. I hope it helps you!

Writing a blog article

With the @nuxt/content module activated you can start with ease to write blog articles. ALl you should be doing is create a content directory in the root of your project directory and create files inside it. Generally you can place your article files directly inside the content directory. But if you plan to host files other than blog articles with the content module, I would suggest to create your articles inside /content/blog or any subdirectory of your choice. I strongly recommend to place the markdown articles into a subdirectory. You will understand the reason while reading through this article!

---
title: "article1"
---

## About this article
You can write any markdown content here and it can be easily displayed later!

As you see in the example above I have added YAML front matter block. All the items added will be injected into the article object and you will be able to see them when you fetch the article object. This can be really helpful if you want to add some properties to the article. You can even set the title, date, author details or anything else in the markdown file and later fetch, use them as you like.

All of your general content goes below the front matter block. You can do everything that you can do with a markdown file. On top of that you can even use html and vue components in the markdown file and with the magic of the module, it will be rendered properly. Which means you can customize your content in the markdown file completely! Also the content module provides syntax highlighting using PrismJS. So you can even demonstrate codeblock examples!

There is a lot more to writing content though. You can definitely check it out here!

Fetching the blog article

Writing alone is not enough right? You would want to fetch the articles and display them. So why not look into fetching the articles next.

Fetching the contents is really really easy. The content module globally injects a $content instace, so you can access it anywhere within the project; either this.$content or context.$content based upon where you use it. That is really easy, isn't it?

Based upon the usage, I can think up of two specific ways you would want to fetch the content. We will look into both the usage methods below.

Fetching all the articles to list them out
Fetching a specific article to display it's content

The first use case for fetching the articles is to list them out. While fetching the article list you would either want to fetch all the articles or even filter the articles based upon some parameters. Here is how you would do that:

// Fetching all the article list
const articles = await this.$content('blog').fetch();

// Fetching articles with filters
const articles = await this.$content('blog')
  .search('title', 'welcome')
  .fetch();

// Fetching specific article [1]
const article = await this.$content('blog', articleSlug).fetch();

// Fetching specific article [2]
const article = await this.$content('blog')
  .where({ slug: articleSlug })
  .fetch();

The first method seen in the example above fetches all the articles inside the /content/blog directory.
The second method also fetches all the articles inside the /content/blog but returns result matching the search criteria. Useful when you are implement a search bar!
The third method fetches a specific article based upon the second parameter passed to it. You get an object instead of array when fetching in this method!
The last method is just an alternative to the third method. It returns an array instead of Object, so you might want to treat it as an array! Speaking from experience already...

You might now always want all the properties of the content. For e.g. when listing title only, you can simply get only the title of the articles using the .only() method i.e. .only(['title']). You can even limit the number of items in the result using the .limit(n) chainable method. Also you can skip number of results using the .skip() method.

I personally use the last method to fetch a specific article and I would even suggest you to do so. It is because it will work even if you decide to change the structure of your content directory and more stuffs here and there. I personally do that a lot! But for the earlier method i.e. you will have to know the exact file location otherwise you will not be able to fetch it.

The content module provides way more control over how you fetch the articles. There is just too many possibilities how you can control fetching your content. It is as good as impossible to know about your specific use case. Thus to know how to customize your fetch request you can have a look here!

Displaying the blog article

This has to be the most easiest task throughout this article. The content module provides a use-and-enjoy component which we will be simply using to display the content of our blog article.

<template>
  <div>
    <nuxt-content :document="article">
  </div>
</template>

The above example will simply display the content of the fetched article. How you customize the page is completely upto you yet again. The article passed into the document prop is the object that we obtained after fetching specific article after the dyanmic slug param. Theoritically that is all you should do to display the content of the article. But you would love to add more details right? You can simply modify the page template to show off your imagination!

Furthermore your page design will not be included into the markdown content. Thus if you want to customize the markdown with custom style you will have to do that like:

/* Making the h2 component have red color. This is just me, you don't have be bad with examples! */
.nuxt-content h2 {
  color: red;
}

A live example of the usage can be found here! I too have used the same thing... No copyright please!

Working with dynamic routes

The core concept of this article is working with static generate site. So we will have to specify all the routes (the article list for us) while generating the site. This too is really easy with the content module. With that simple addition of the code below to nuxt.config.js your site will be ready to handle the dyanmic article page.

export default {
  modules: [
    '@nuxt/content'
  ],
  generate: {
    async routes() {
      const { $content } = require('@nuxt/content');
      const articles = await $content('blog').only(['slug']).fetch();

      // Generating the routes for the unique page of each article...
      return articles.map((article) => `/article/${article.slug}`);
    }
  }
}

NOTE: From 2.13+, nuxt export is said to have a crawler integrade to the core module. Which means the code above will not have to be injected into your config file!

That has to be all with the development of a basic markdown powered blog using nuxt and nuxt-content. If you did everything right then your blog should be working as well. If not just tell me in the comments below!

Also like any other module, content also provides customization options so that you can customize the behavious as you like. You can check about the customization options here!

Bonus

It was a really long article to write and I am preety sure it was hard to read it all as well. So I thought about sharing some interesting things with you guys. I actually wanted to list out points/stuffs which you might find interesting, and you can even integrate it with the blog you will be making with the awesome content module:

Netlify: Host the blog you created right away!
Implement reading time: You can implement reading time in your articles. Details are from the official nuxt-content module!
Sitemap: Let the web crawlers know each and every of your content!
Blog feeds: Let your community know when articles are out!
Nuxt color mode: Which do you prefer, day or night ??
Nuxt components: Get rid of those component imports that occur everywhere. Comes with core nuxt 2.13+
Disqus: I love user engaged community!
- vue-disqus to make things easy.
- Optionally you can go for facebook comment plugin or other comment plugin provider!
This site is a live example and demo of using this article! Lots of changes will be made to the site and article itself to show what more you can do with it!

I am always open for feebacks ❤️ Originally posted on my blog here