Backend Weekly
Posts
API and API Design: How Do Simple JSON APIs Work?

API and API Design: How Do Simple JSON APIs Work?

We will discuss one API style called Simple JSON APIs, we will look at how Simple JSON APIs work and the different components of Simple JSON APIs.

Solomom Eseme
December 04, 2024

In partnership with

Hello “👋

Welcome to another week, another opportunity to become a Great Backend Engineer.

Today’s issue is brought to you by Masteringbackend → A great resource for backend engineers. We offer next-level backend engineering training and exclusive resources.

Before we get started, I have a few announcements:

I have a special gift for you: You will love this one.

Unlock Windsurf Editor, by Codeium.

Introducing the Windsurf Editor, the first agentic IDE. All the features you know and love from Codeium’s extensions plus new capabilities such as Cascade that act as collaborative AI agents, combining the best of copilot and agent systems. This flow state of working with AI creates a step-change in AI capability that results in truly magical moments.

Download It Free Today

Now, back to the business of today.

In my previous series, I explored everything you need to know and learn about API and API Designs: Different API Styles.

Today, we will discuss one API style called Simple JSON APIs, we will look at how Simple JSON APIs work and the different components of Simple JSON APIs.

This comes from my Backend Engineering Hub under the API and API Design section. However, I’m only transferring the knowledge here and breaking it down in this series one topic at a time.

Before we move on If you enjoy this newsletter. Invite your friends and get my books for free.

How Do Simple JSON APIs Work?

Simple JSON APIs have become a cornerstone of modern web and mobile app development in the digital age of connected applications.

They provide a lightweight, efficient, and intuitive way to exchange data between a client and a server. JSON (JavaScript Object Notation) plays a central role in this process, thanks to its simplicity and compatibility with various programming languages.

What is a JSON API?

A JSON API is an API that uses JSON as its data format for communication between a client (frontend) and a server (backend). JSON APIs facilitate seamless data exchange by structuring information into key-value pairs.

With its human-readable and lightweight structure, JSON is ideal for APIs designed to perform CRUD operations (Create, Read, Update, Delete) on data. Its versatility has made it the de facto standard for web APIs in various domains, from e-commerce to social media platforms.

How Do JSON APIs Work?

The workflow of a Simple JSON API can be broken down into three primary steps:

The client makes a Request

A client application (e.g., a web browser, mobile app, or IoT device) sends an HTTP request to the API server. The request specifies:

HTTP Method: Indicates the type of operation (GET, POST, PUT, DELETE, etc.).
Endpoint: The URL of the API resource being accessed.
Headers: Metadata, including content type (application/json) and authorization tokens (if required).
Payload (Body): Data sent in the request body (typically for POST or PUT methods).

Example Request

Here’s an HTTP POST request to create a new user:

POST /api/users HTTP/1.1  
Host: example.com  
Content-Type: application/json  

{  
  "name": "John Doe",  
  "email": "[email protected]",  
  "password": "securePassword123"  
}

The server Processes the Request

The server processes the request in several steps:

Routing: The server determines the endpoint and matches it with the correct handler.
Validation: It validates the request data to adhere to the API's rules.
Database Interaction: The server interacts with the database (if needed) to perform the requested operation.
Response Creation: After processing, the server sends back a response in JSON format.

Example Backend Code (Node.js)

const express = require('express');
const app = express();

app.use(express.json());

// Endpoint to create a new user
app.post('/api/users', (req, res) => {
  const { name, email, password } = req.body;

  // Simulate saving user to a database
  const newUser = { id: 1, name, email };

  res.status(201).json({
    message: 'User created successfully',
    data: newUser,
  });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Client Receives a Response

The server sends a response back to the client. The response contains:

HTTP Status Code: Indicates the outcome (e.g., 200 OK, 201 Created, 400 Bad Request).
Headers: Metadata such as Content-Type: application/json.
Body: A JSON payload with the result of the operation.

Example Response:

{
  "message": "User created successfully",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]"
  }
}

The client processes this response and updates the UI or performs further actions as needed.

Why Are JSON APIs So Popular?

Lightweight and Fast: JSON’s compact structure reduces payload size, making APIs faster and more efficient.
Human-Readable: JSON’s syntax is easy to read, write, and debug.
Cross-Language Support: Virtually all programming languages support JSON parsing.
Flexibility: JSON APIs are versatile and can represent complex data structures like arrays and nested objects.
Widespread Adoption: JSON APIs are supported by modern tools, frameworks, and libraries, making them a go-to choice for developers.

Design Principles for Simple JSON APIs

Use Clear and Intuitive Endpoints: Design endpoints that clearly describe the resource they represent.

GET /api/users – Fetch all users.
GET /api/users/{id} – Fetch a specific user.

Consistent Use of HTTP Methods: Adopt standard HTTP methods for different operations:

GET: Retrieve data.
POST: Create new resources.
PUT/PATCH: Update resources.
DELETE: Remove resources.

Return Meaningful HTTP Status Codes: Always return appropriate status codes to reflect the result of the operation.

200 OK – Request succeeded.
201 Created – Resource successfully created.
400 Bad Request – Invalid request data.
401 Unauthorized – Missing or invalid authentication.

Structure JSON Responses Properly: Organize JSON responses to include metadata, data, and error information.

{
  "success": true,
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]"
  },
  "error": null
}

Secure the API: Use authentication (e.g., Token-Based Auth, OAuth) and HTTPS to protect data in transit.

Advantages of Simple JSON APIs

Ease of Integration: Simple JSON APIs are straightforward to implement and consume.
Scalability: They work seamlessly across devices, platforms, and networks.
Developer-Friendly: Widely supported by tools and frameworks, JSON APIs speed up development.
Reduced Overhead: Smaller payloads mean better performance, especially for mobile applications.

Simple JSON APIs are the backbone of modern application development. By leveraging JSON's lightweight, readable structure, these APIs enable seamless communication between clients and servers. Their simplicity, combined with robust design principles, makes them a preferred choice for developers building scalable and efficient web and mobile applications.

Whether you are developing a small app or a large enterprise system, mastering Simple JSON APIs is a key step toward creating robust and user-friendly solutions.

Did you learn any new things from this newsletter this week? Please reply to this email and let me know. Feedback like this encourages me to keep going.

See you on Next Week.

Remember to start learning backend engineering from our courses:

Get a 50% discount on any of these courses. Reach out to me (Reply to this mail)

Backend Engineering Resources

Whenever you're ready

There are 4 ways I can help you become a great backend engineer:

1. The MB Platform: Join 1000+ backend engineers learning backend engineering on the MB platform. Build real-world backend projects, track your learnings and set schedules, learn from expert-vetted courses and roadmaps, and solve backend engineering tasks, exercises, and challenges.

2. The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering BootCamp to produce great backend engineers.

3. MB Video-Based Courses: Join 1000+ backend engineers who learn from our meticulously crafted courses designed to empower you with the knowledge and skills you need to excel in backend development.

4. GetBackendJobs: Access 1000+ tailored backend engineering jobs, manage and track all your job applications, create a job streak, and never miss applying. Lastly, you can hire backend engineers anywhere in the world.

LAST WORD 👋

How am I doing?

I love hearing from readers, and I'm always looking for feedback. How am I doing with The Backend Weekly? Is there anything you'd like to see more or less of? Which aspects of the newsletter do you enjoy the most?

Hit reply and say hello - I'd love to hear from you!

Stay awesome,
Solomon

I moved my newsletter from Substack to Beehiiv, and it's been an amazing journey. Start yours here.

Reply

or to participate.