The Art of API Design: Lessons Learned in Building VividBlog

The old adage, "Measure twice, cut once," applies perfectly to API design. A well-designed API is the foundation for a robust and maintainable application. In this post, I'll share my experiences designing the API for VividBlog, a blog platform I recently built, highlighting the importance of thorough planning and the thought processes behind key decisions.

Three-Layer Cake-Structure🎂

I always take API's as a 3 layer structure

I approach APIs with a three-layer structure:

• Database Layer: The rock-solid foundation holding your data.
• Schema Layer: The validation gatekeeper ensuring data integrity.
• Endpoint Layer: The public interface where developers interact with your API.

Designing for Flexibility: Database-First vs. UI-Mockup First

While I tackled VividBlog's design database-first due to resource constraints, there's no one-size-fits-all approach. Here's how to choose the right path:

• Database-First: Ideal for data-centric APIs where data integrity and structure are paramount. Think financial transactions or inventory management systems.
• UI-Mockup First: Great for user-driven APIs where a seamless user experience is crucial. E-commerce applications or social media platforms benefit from this approach.

The key lies in finding a balance. Even without a full UI mockup, sketching core functionalities and data models provides a valuable starting point.

In the absence of a finalized UI design, I adopted a data-centric approach to schema design. This involved creating separate schemas for:

• The JSON data expected in the request payload...
• The JSON data returned in the response payload...

---

Building the Foundation: Flask-RESTful, Marshmallow and SQLAlchemy

For building the VividBlog API, I opted for a popular combination of tools:

• Flask-RESTful: A lightweight framework within the Flask ecosystem that simplifies building RESTful APIs in Python.
• Marshmallow: A powerful data validation library that streamlines the process of ensuring data sent in requests adheres to the expected format.

This combination provides a robust and efficient foundation for API development.

Database Choices: Balancing Flexibility and Structure

While I initially explored SQLite for its simplicity, I ultimately decided to leverage SQLAlchemy as the Object-Relational Mapper (ORM). SQLAlchemy offers several advantages:

• Database Agnosticism: It allows working with various database backends like PostgreSQL, MySQL, or SQLite. This provides flexibility in choosing the most suitable database for your project's needs.
• Data Modeling: SQLAlchemy facilitates robust data modeling through its ORM capabilities, allowing you to define data structures that closely resemble your application objects.

While SQLite offers a convenient lightweight option, its data definition approach can be less strict compared to PostgreSQL. For projects requiring strong data integrity and complex data relationships, PostgreSQL often emerges as the preferred choice.

Key Takeaway: Choosing the Right Tools

The choice of frameworks and databases depends on your project's specific requirements. Consider factors like scalability, data complexity, and team familiarity when making these decisions.

---

Resources: Modelling your API's with Collections and Singletons

Effective API design involves representing your data models as resources. This section explores two key resource types:

• Collection Resources: Represent a collection of similar data items. In VividBlog, this could be a list of all blog posts, potentially filtered by criteria like category or author.
• Singleton Resources: Represent a single, unique data item. For VividBlog, this might be a specific blog post identified by its unique ID.

The Power of the Pair:

It's generally recommended to create both collection and singleton resources for each data model in your API. This provides a consistent and flexible way to interact with your data:

• Collection Resources: Ideal for browsing, searching, and filtering through multiple data items.
• Singleton Resources: Perfect for retrieving, creating, updating, or deleting a specific data item.

Example: VividBlog's Blog Posts

Consider VividBlog's blog posts stored in a database table or relation named "blog." Here's how these resources would be implemented:

1. Collection Resource: An endpoint like /api/v1/blogs might return a list of all blog posts, potentially filtered by parameters like name or author_id.
2. Singleton Resource: An endpoint like /api/v1/blogs/123 (where 123 is the unique ID of a specific blog post) would return details about that particular post.

---

Schema and Validation

Marshmallow plays a crucial role in VividBlog's API by providing data validation for both incoming and outgoing data. This ensures data integrity and streamlines communication between the API and client applications.

Separate Schemas for Distinct Purposes:
I implemented two distinct Marshmallow schemas for each data model:

1. Request Schema: This schema defines the expected structure and validation rules for data sent in API requests. It acts as a gatekeeper, ensuring only valid data reaches the backend logic.
2. Response Schema: This schema dictates the format of data returned in API responses. It defines the data structure and any transformations applied to the data before serialization.

Example: User Management Schemas

Consider the user model in VividBlog. Here are the corresponding Marshmallow schemas:

1. CreateUserSchema: This schema would likely include fields for username, email, and password (hashed for security). It would enforce validation rules like required fields and email format.
2. UserItemSchema: This schema might include the user's ID, username, email (if appropriate for the response context), and potentially other relevant user data. It would determine which data is included in the response and how it's formatted.

By separating request and response schemas, you achieve clear separation of concerns and ensure data validation happens at the appropriate stage of the API interaction.

To illustrate schema design, let's look at a simplified example using Marshmallow for user data:

from marshmallow import Schema, fields

class CreateUserSchema(Schema):
  username = fields.Str(required=True)
  email = fields.Email(required=True)

class UserItemSchema(Schema):
  id = fields.Integer(read_only=True)
  username = fields.Str()
  email = fields.Email()
  created_at = fields.DateTime(read_only=True)

The CreateUserSchema validates incoming user data, while UserItemSchema defines the response structure, excluding automatically generated fields like id and created_at.

---

Login

VividBlog utilizes JSON Web Tokens (JWTs) for user authentication. JWTs are a popular and secure mechanism for transmitting authentication information between a client and a server. They offer several advantages:

• Security: JWTs are self-contained and digitally signed, making them tamper-proof and preventing unauthorized access.
• Statelessness: The server doesn't need to store session data, simplifying architecture and improving scalability.
• Flexibility: JWTs can encode additional user information beyond just authentication status, allowing for role-based authorization.

For a deeper understanding of JWTs and their implementation, I recommend exploring resources dedicated to JWT authentication best practices.

---

Efficient Data Navigation: Pagination and Query Parameters

VividBlog employs pagination to allow users to navigate through large datasets of blog posts efficiently. Pagination breaks down data into manageable chunks (pages) that users can navigate through using query parameters.

The Art of Pagination:

Designing an effective pagination scheme involves several considerations:

• Choosing the Right Approach: There are two main pagination strategies: offset-based and cursor-based. VividBlog utilizes offset-based pagination, where currentPage and pageSize parameters define the starting point and number of items per page in the requested data.
• Clear and Readable URIs: I opted for camelCase query parameters (currentPage and pageSize) to enhance the readability of URIs. This makes it easier for developers to understand the purpose of each parameter at a glance.
• Handling Edge Cases: A robust pagination system should handle edge cases like empty pages or exceeding the total number of items. This might involve returning appropriate error messages or adjusting the requested page number.

Example: Paginating Blog Posts

Imagine a scenario where VividBlog has 50 blog posts. Here's how pagination would work:

• A request with currentPage=1 and pageSize=10 would retrieve the first 10 blog posts.
• A request with currentPage=3 and pageSize=10 would retrieve posts 21 to 30 (assuming there are at least 30 posts).

Beyond Pagination: Leveraging Query Parameters

Query parameters can extend beyond pagination. VividBlog might also allow filtering posts by parameters like name or author_id. This empowers users to refine their search results and find the information they need quickly
By carefully considering these elements, you can design a pagination system that offers a smooth and efficient user experience while maintaining clean and readable URIs.

---

Importance of designing API's

Beyond Time Saved: The Power of Thorough Design

The time saved by meticulous design goes beyond just a few initial weeks. Here's how a well-designed API pays dividends in the long run:

• Maintainability: A clear and logical structure makes it easier for developers to understand, modify, and extend the API as your project evolves.
• Scalability: A well-designed foundation can accommodate increased usage without buckling under pressure.
• Consistency: Developers using your API will experience a uniform and predictable interaction, streamlining development efforts.
• Documentation: A well-organized API with clear logic is easier to document, making it more accessible to a wider developer audience.

---

What would you do differently?

I'm always looking for ways to improve my API design skills. If you've encountered similar challenges or have insights on how I could have approached VividBlog's design differently, please share your thoughts in the comments below! Engaging in this conversation can help all of us build even better APIs in the future.