RealWorld API Article Response Structure: Complete JSON Format Guide

When querying article endpoints in the RealWorld API, the server returns a JSON object containing an articles array and an articlesCount integer, with each article transformed by the articleMapper function before serialization.

The RealWorld API provides a standardized backend specification for testing frontend implementations. When building clients that consume article data from the gothinkster/realworld repository, understanding the exact RealWorld API article response structure ensures your components parse the JSON correctly across all list and feed endpoints.

Top-Level Response Properties

Every article query endpoint returns a consistent wrapper object with two properties.

The articles Array

The articles property contains an array of article objects matching your query criteria. According to the route handlers in apps/api/server/routes/api/articles/index.get.ts and apps/api/server/routes/api/articles/feed.get.ts, the system packages the transformed data as { articles, articlesCount } before sending the response.

The articlesCount Field

The articlesCount property is an integer representing the total number of articles satisfying the query parameters, ignoring pagination limits. This value enables frontend clients to calculate total pages for pagination controls.

Article Object Schema

Each object inside the articles array follows the structure defined in apps/api/server/utils/article.mapper.ts. The articleMapper utility converts raw database rows into the public API shape.

Core Article Fields

• slug: URL-friendly identifier string (e.g., "how-to-code-123")
• title: Article title string
• description: Short summary string
• body: Full content string (omitted from list endpoints via omit: { body: true })
• tagList: Array of strings representing attached tags
• createdAt: ISO-8601 date string of creation timestamp
• updatedAt: ISO-8601 date string of last update timestamp

Engagement and Author Data

• favorited: Boolean indicating if the requesting user has favorited the article (defaults to false for unauthenticated requests)
• favoritesCount: Integer count of total users who favorited the article
• author: Object containing username, image, and followedBy boolean properties (mapped via author.mapper.ts)

Source Code Implementation

The response structure is assembled in specific route handlers and utility functions within the repository.

Route Handlers

In apps/api/server/routes/api/articles/index.get.ts, the global article list handler executes the query, retrieves both the paginated results and total count, and returns them as a structured object. The personalized feed endpoint in apps/api/server/routes/api/articles/feed.get.ts follows an identical pattern but filters by followed authors.

Data Transformation

The articleMapper function in apps/api/server/utils/article.mapper.ts handles the transformation logic, ensuring consistent field naming and calculating the favorited status based on the requesting user's ID.

Practical Query Examples

The following examples demonstrate how to request and handle the article response structure against the live RealWorld API.

Fetching Global Articles with cURL

curl -s "https://api.realworld.io/api/articles?limit=5&offset=0" \
  -H "Accept: application/json"

Expected Response:

{
  "articles": [
    {
      "slug": "how-to-code-123",
      "title": "How to code",
      "description": "A short guide",
      "tagList": ["programming", "tutorial"],
      "createdAt": "2024-09-01T12:34:56.789Z",
      "updatedAt": "2024-09-02T08:20:10.123Z",
      "favorited": false,
      "favoritesCount": 3,
      "author": {
        "username": "johndoe",
        "image": "https://api.realworld.io/images/johndoe.jpg",
        "followedBy": false
      }
    }
  ],
  "articlesCount": 42
}

Consuming the API with JavaScript Fetch

async function loadArticles(page = 1, limit = 10) {
  const offset = (page - 1) * limit;
  const res = await fetch(
    `https://api.realworld.io/api/articles?limit=${limit}&offset=${offset}`,
    { headers: { Accept: "application/json" } }
  );
  const { articles, articlesCount } = await res.json();

  console.log(`Total articles: ${articlesCount}`);
  return { articles, articlesCount };
}

Authenticated Feed Request

When accessing the personalized feed at GET /api/articles/feed, include an authorization header. The response structure remains identical to the global list, but filters to articles by followed authors:

curl -s "https://api.realworld.io/api/articles/feed?limit=5" \
  -H "Authorization: Token <YOUR_JWT>"

Summary

• The RealWorld API article response structure always includes articles (array) and articlesCount (integer) at the top level.
• Article objects contain metadata fields (slug, title, description), timestamps, tag arrays, and engagement metrics (favorited, favoritesCount).
• The body field is intentionally omitted from list endpoints to reduce payload size.
• The articleMapper utility in apps/api/server/utils/article.mapper.ts standardizes the transformation from database records to API responses.
• Route handlers in index.get.ts and feed.get.ts package the data consistently across global and personalized feeds.

Frequently Asked Questions

What endpoints return the articles response structure?

The endpoints GET /api/articles, GET /api/articles?author={username}, GET /api/articles?tag={tag}, GET /api/articles?favorited={username}, and GET /api/articles/feed all return the same JSON structure containing the articles array and articlesCount integer.

Why is the article body missing from the response?

The body field is excluded from list responses via the omit: { body: true } configuration in the query options to optimize performance. You must call GET /api/articles/{slug} to retrieve the full article body.

How does the API calculate the favorited field?

The favorited boolean reflects whether the requesting user's ID appears in the article's favorites list. For unauthenticated requests, this value defaults to false as implemented in the articleMapper logic.

What is the default pagination limit for article queries?

The default limit parameter is 10 articles per request, controlled by the route handlers in apps/api/server/routes/api/articles/index.get.ts and feed.get.ts. Use the offset parameter to paginate through results.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}