TEST - Success Response Structure | DOCS

Overview

When API requests succeed, the SweetConnect Platform returns a consistent response structure with a data field containing the requested resource or result.

Success Response Format

All successful responses follow this structure:

{
  "data": {
    // Resource data or result
  }
}

HTTP Status Codes

Successful responses use 2xx status codes:

Status Code	Meaning	When Used
200 OK	Request succeeded	GET, PUT, DELETE operations
201 Created	Resource created successfully	POST operations creating new resources
204 No Content	Success with no response body	DELETE operations (alternative to 200)

Response Types

Single Resource Response

When fetching or updating a single resource:

Request:

GET /api/assets/asset-123
Authorization: Bearer <token>

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": "asset-123",
    "name": "Machine A",
    "assetType": "Machine",
    "serialNumber": "SN-12345",
    "state": "ACTIVE",
    "isDraft": false,
    "parentId": "plant-456",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  }
}

List Response

When fetching multiple resources:

Request:

GET /api/assets
Authorization: Bearer <token>

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "asset-123",
      "name": "Machine A",
      "assetType": "Machine"
    },
    {
      "id": "asset-456",
      "name": "Machine B",
      "assetType": "Machine"
    }
  ]
}

Paginated List Response

When fetching large collections with pagination:

Request:

GET /api/assets?page=1&limit=20
Authorization: Bearer <token>

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "items": [
      {
        "id": "asset-123",
        "name": "Machine A",
        "assetType": "Machine"
      },
      {
        "id": "asset-456",
        "name": "Machine B",
        "assetType": "Machine"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalItems": 156,
      "totalPages": 8
    }
  }
}

Empty Response (Void)

When operation succeeds with no data to return:

Request:

PUT /api/assets/asset-123/activate
Authorization: Bearer <token>

Response (Option 1 - with undefined):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": undefined
}

Response (Option 2 - No Content):

HTTP/1.1 204 No Content

Created Resource Response

When creating a new resource:

Request:

POST /api/assets
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Machine C",
  "assetType": "Machine",
  "serialNumber": "SN-67890"
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/assets/asset-789

{
  "data": {
    "id": "asset-789",
    "name": "Machine C",
    "assetType": "Machine",
    "serialNumber": "SN-67890",
    "state": "INACTIVE",
    "isDraft": false,
    "createdAt": "2024-11-05T10:00:00Z",
    "updatedAt": "2024-11-05T10:00:00Z"
  }
}

Response Consistency

Key Principles

Always wrapped in data: Success responses always have a data field
Type consistency: Same endpoint always returns same data structure
Timestamps: All resources include createdAt and updatedAt in ISO 8601 format
IDs: All resources have a unique id field
Null vs undefined: Optional fields use undefined when not set

Success vs Error Responses

Success Response:

{
  "data": { /* resource */ }
}

Error Response:

{
  "errors": [ /* error objects */ ]
}

Client Detection:

if (response.data.data !== undefined) {
  // Success response
  handleSuccess(response.data.data);
} else if (response.data.errors) {
  // Error response
  handleErrors(response.data.errors);
}

Next Steps

Error Response Structure - Understanding error responses

Success Response Structure

On this page