<aside> đź“–

API design involves making intentional decisions about how an API will expose data to consumers. These decisions are then captured in an API definition, which is a human- and machine-readable representation of an API's intended functionality. API definitions adhere to API specifications, such as OpenAPI and AsyncAPI, which provide a standardized format and vocabulary for API definitions and lay the foundation for API contracts, documentation, mocks, and tests.

Leaders may wish to standardize the design stage by defining organizational patterns and practices for shaping the surface area and behavior of APIs. For instance, they may require that all teams follow the OpenAPI specification, and they may also define style rules for capitalization, naming, and punctuation that can be enforced through automated checks.

</aside>

API Design Decisions

Endpoint Structure

I wanted to keep our mvp simple. One endpoint will be for displaying posts to allow for browsing. The other will be for viewing the details of an individual post. I chose slug-based URLs over numeric IDs because they're more readable, stable (won't break if posts are reordered), and SEO-friendly for potential future frontend applications.

Base URL: /api/v1/

Main Endpoints:

  1. List Posts: GET /api/v1/posts/
  2. Post Detail: GET /api/v1/posts/{slug}/

Response Format

List Posts Request/Response:

The request/response format is a result of using drf’s pagination. I chose PageNumberPagination over LimitOffset because it's more user-friendly for browsing (users think in pages, not offsets) and simpler to implement.

**Request:**
GET <https://api.example.org/api/v1/posts/?page=3>

**Response:**
HTTP 200 OK
{
    "count": 1023,
    "next": "<https://api.example.org/api/v1/posts/?page=4>",
    "previous": "<https://api.example.org/api/v1/posts/?page=2>",
    "results": [
       {
			    "title": "Post Title",
			    "published_at": "2025-08-28", 
			    "url": "<http://localhost:8000/api/v1/posts/post-title/>"
			  }
       ...
    ]
}

Post Detail Request/Response:

**Request:**
GET <https://api.example.org/api/v1/posts/{slug}>

**Response:**
{
  "title": "Post Title",
  "author": "Author Name", 
  "published_at": "2025-08-28",
  "content": "<p>Full HTML content here</p>"
}

Filtering & Search

Filtering and searching was kept simple. I plan on using django-filter for the filtering.

I chose date ranges over year/month filters because they're more flexible. Users can query 'last 30 days' with the same API. I included author, title, and content search to make it easier to look for posts when a user only remembers a few details.

Search Parameters: