Software Architect Guide: Designing a RESTful API for a 🌐 Multi-Tenant Blogging Platform

Building a multi-tenant blogging platform requires thoughtful design of the API to ensure clarity, scalability, and security. In this post, we’ll explore a RESTful API design including versioning, nested resources, and authentication, using clear examples and best practices.

🧩 Understanding the Requirements

Before diving into endpoints, let’s break down what the platform supports:

• Multiple tenants (e.g., organizations, teams)
• Each tenant has users
• Users can create blogs, and each blog has posts
• Posts can have comments
• Authentication is required

📁 Versioning

We’ll use URI-based versioning:

/api/v1/

This helps manage breaking changes cleanly.

🔐 Authentication

We’ll use token-based authentication (e.g., JWT or API keys). Each request must include:

Authorization: Bearer <token>

📌 Base URL

https://api.blogcloud.com/api/v1

📚 API Endpoint Design

🔸 Tenants

Tenants are top-level entities.

• GET /tenants – List all tenants (admin only)
• POST /tenants – Create a new tenant
• GET /tenants/:id – Show tenant details
• PATCH /tenants/:id – Update tenant
• DELETE /tenants/:id – Delete tenant

🔸 Users (Scoped by tenant)

• GET /tenants/:tenant_id/users – List users for tenant
• POST /tenants/:tenant_id/users – Create user
• GET /tenants/:tenant_id/users/:id – Show user
• PATCH /tenants/:tenant_id/users/:id – Update user
• DELETE /tenants/:tenant_id/users/:id – Delete user

🔸 Blogs (Belong to users)

• GET /tenants/:tenant_id/users/:user_id/blogs – List blogs
• POST /tenants/:tenant_id/users/:user_id/blogs – Create blog
• GET /tenants/:tenant_id/users/:user_id/blogs/:id – Show blog
• PATCH /tenants/:tenant_id/users/:user_id/blogs/:id – Update blog
• DELETE /tenants/:tenant_id/users/:user_id/blogs/:id – Delete blog

🔸 Posts (Belong to blogs)

• GET /blogs/:blog_id/posts – List posts
• POST /blogs/:blog_id/posts – Create post
• GET /blogs/:blog_id/posts/:id – Show post
• PATCH /blogs/:blog_id/posts/:id – Update post
• DELETE /blogs/:blog_id/posts/:id – Delete post

🔸 Comments (Belong to posts)

• GET /posts/:post_id/comments – List comments
• POST /posts/:post_id/comments – Add comment
• DELETE /posts/:post_id/comments/:id – Delete comment

❓Question: what is the full url of comments?

No, the full URL for comments should not be:

https://api.blogcloud.com/api/v1/tenants/:tenant_id/users/:user_id/blogs/posts/:post_id/comments

That nesting is too deep and redundant, because:

• By the time you’re at a post, you already implicitly know which blog/user/tenant it’s under (assuming proper authorization).
• Posts have unique IDs across the system (or at least within blogs), so we don’t need the entire hierarchy in every request.

✅ Correct RESTful URL for Comments

If your post_id is unique (or unique within a blog), the cleanest design is:

https://api.blogcloud.com/api/v1/posts/:post_id/comments

or, if you prefer to keep blog_id context:

https://api.blogcloud.com/api/v1/blogs/:blog_id/posts/:post_id/comments

Use that second version only if post_id is not globally unique, and you need the blog context.

🔁 Recap of Comments Endpoints

🧠 Design Rule of Thumb

• ✅ Keep URLs meaningful and shallow.
• ❌ Don’t over-nest resources unless it’s needed to enforce scoping or clarify context.

📥 Example: Create a Blog Post

Request:

POST /blogs/123/posts
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Why REST APIs Still Matter",
  "body": "In this post, we explore the benefits of RESTful design..."
}

Response:

201 Created
{
  "id": 456,
  "title": "Why REST APIs Still Matter",
  "body": "In this post, we explore the benefits of RESTful design...",
  "created_at": "2025-07-03T10:00:00Z"
}

✅ Best Practices Followed

• Nesting: Resources are nested to show ownership (e.g., blogs under users).
• Versioning: Prevents breaking old clients.
• Consistency: Same verbs and JSON structure everywhere.
• Authentication: Every sensitive request requires a token.

🧠 Final Thoughts

Designing a RESTful API for a multi-tenant app like a blogging platform requires balancing structure and simplicity. By properly scoping resources, using versioning, and enforcing auth, you build an API that’s powerful, secure, and easy to maintain.

Bonus Tip: Document your API using tools like Swagger/OpenAPI to make onboarding faster for new developers.

You are an awesome Architect 🚀

Author: Abhilash

Hi, I’m Abhilash! A seasoned web developer with 15 years of experience specializing in Ruby and Ruby on Rails. Since 2010, I’ve built scalable, robust web applications and worked with frameworks like Angular, Sinatra, Laravel, Node.js, Vue and React. Passionate about clean, maintainable code and continuous learning, I share insights, tutorials, and experiences here. Let’s explore the ever-evolving world of web development together! View all posts by Abhilash