Response envelopes and resource models

Use the top-level envelope to select the resource returned by a Conduit operation, then parse the resource fields described here. Successful JSON responses should use Content-Type: application/json; charset=utf-8.

Response structure

Every success payload is an object whose property identifies the resource or collection. Do not deserialize the response as a bare article, user, or array.

The diagram shows the parsing boundary: first select the named envelope, then read the resource or collection inside it. An article list also carries articlesCount, which is the total number of matching articles independent of the current page.

Success envelopes

Examples of the collection boundaries:

{
  "articles": [],
  "articlesCount": 0
}

{
  "tags": ["reactjs", "angularjs"]
}

An empty collection is still a successful named envelope. Treat [] and 0 as data, not as a missing response.

User and profile

The user object contains these required properties: email (string), token (string), username (string), bio (string or null), and image (string or null). The token is returned by registration or login and is used in the Authorization: Token <jwt> header for protected operations.

The profile object contains username (string), bio (string or null), image (string or null), and following (boolean). The same profile shape is nested in an article's author and a comment's author.

Article

An article has the following required fields:

Article collections contain these same article fields and are returned newest-first according to the documented response behavior. Use pagination to combine articles with articlesCount.

Comment

A comment contains id (integer), createdAt (date-time string), updatedAt (date-time string), body (string), and author (Profile object). A comments response wraps the array in comments; it does not return a bare array.

Errors and next steps

Error responses use an errors object rather than one of the success envelopes. Follow errors to map status codes and field messages, and authentication to send the user token correctly.

Example parser

const payload = await response.json();
if (!response.ok) {
  throw new Error(JSON.stringify(payload.errors));
}

const articles = payload.articles ?? [];
const total = payload.articlesCount ?? articles.length;

The fallback above is appropriate only after confirming the operation is an article-list operation; do not use it to hide a malformed envelope from another endpoint.

Next step

Use the resource-specific endpoint guides to send and consume these shapes, beginning with list and filter articles.