API Design

REST API Response JSON Example

A standardized JSON example for a REST API response envelope — includes data, status, meta, and pagination fields. Copy-ready template for consistent API response design.

JSON

Open in Formatter

{
  "success": true,
  "status": 200,
  "message": "Users fetched successfully.",
  "data": [
    {
      "id": "usr_9k2mXpQr4t",
      "fullName": "Ravi Mehta",
      "email": "ravi.mehta@example.com",
      "role": "admin"
    },
    {
      "id": "usr_3hFwLmNz8q",
      "fullName": "Priya Sharma",
      "email": "priya.sharma@example.com",
      "role": "editor"
    }
  ],
  "meta": {
    "total": 84,
    "page": 1,
    "perPage": 20,
    "totalPages": 5
  },
  "links": {
    "self": "https://api.example.com/v1/users?page=1",
    "next": "https://api.example.com/v1/users?page=2",
    "prev": null,
    "first": "https://api.example.com/v1/users?page=1",
    "last": "https://api.example.com/v1/users?page=5"
  },
  "requestId": "req_Xm9pKv3LqR",
  "timestamp": "2025-05-01T10:30:00Z"
}

Field Reference

successbooleanrequiredTop-level flag indicating whether the request succeeded

statusintegerrequiredHTTP status code mirrored in the response body

messagestringrequiredHuman-readable status message for debugging

dataarray<object> | objectrequiredThe primary response payload — array for collections, object for single resources

meta.totalintegeroptionalTotal count of records matching the query

linksobjectoptionalHATEOAS-style navigation links for pagination

requestIdstringoptionalUnique identifier for distributed tracing and support

timestampstring (ISO 8601)requiredServer time when the response was generated

Variants

MinimalSimple single-resource success response without pagination or links.

Minimal

Open in Formatter

{
  "success": true,
  "status": 200,
  "message": "User fetched successfully.",
  "data": {
    "id": "usr_9k2mXpQr4t",
    "fullName": "Ravi Mehta",
    "email": "ravi.mehta@example.com"
  },
  "timestamp": "2025-05-01T10:30:00Z"
}

ExtendedFull envelope with nested error details, deprecation warnings, and rate-limit headers.

Extended

Open in Formatter

{
  "success": true,
  "status": 200,
  "message": "Users fetched successfully.",
  "data": [
    {
      "id": "usr_9k2mXpQr4t",
      "fullName": "Ravi Mehta",
      "email": "ravi.mehta@example.com",
      "role": "admin"
    },
    {
      "id": "usr_3hFwLmNz8q",
      "fullName": "Priya Sharma",
      "email": "priya.sharma@example.com",
      "role": "editor"
    }
  ],
  "meta": {
    "total": 84,
    "page": 1,
    "perPage": 20,
    "totalPages": 5,
    "filters": {
      "role": "all",
      "isActive": true
    }
  },
  "links": {
    "self": "https://api.example.com/v1/users?page=1",
    "next": "https://api.example.com/v1/users?page=2",
    "prev": null,
    "first": "https://api.example.com/v1/users?page=1",
    "last": "https://api.example.com/v1/users?page=5"
  },
  "rateLimit": {
    "limit": 1000,
    "remaining": 987,
    "resetAt": "2025-05-01T11:00:00Z"
  },
  "warnings": [
    "This endpoint is deprecated. Use /v2/users instead."
  ],
  "requestId": "req_Xm9pKv3LqR",
  "timestamp": "2025-05-01T10:30:00Z"
}

Common Use Cases

→Establishing a consistent response envelope across all endpoints in an API
→Onboarding frontend teams with a clear, predictable JSON contract
→Generating API documentation and mock server responses

RESTAPIresponseenvelopepagination

Validate or format this JSON

Paste the example above into JSONKit's tools to validate, minify, or explore the structure interactively.

Format →Validate →Minify →

Frequently Asked Questions

It is optional but common. Including 'status' in the body makes the response self-describing when consumed by clients that may lose HTTP context (e.g. message queues, logs).

Single-resource endpoints (GET /users/:id) return an object; collection endpoints (GET /users) return an array. Keeping this consistent prevents client-side type errors.

HTTP status codes are the primary signal, but a 'success' boolean in the body is a convenience for clients that do not inspect status codes deeply, such as mobile apps or no-code integrations.

Related JSON Examples

API DesignError ResponseREST API error JSON with status code, machine-readable error code, and validation details.API DesignPagination ResponsePaginated list response JSON with offset, cursor, total, and navigation links.API DesignUser ProfileStandard user profile JSON with personal info, address, and account metadata.