API Responses

Standard response formats for AsaHome Cloud API.

Response Structure

Successful Responses

All successful responses follow a consistent structure:

Single Resource

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Collection

{
  "data": [
    {
      "id": "device-uuid-1",
      "name": "Home Hub",
      "isOnline": true
    },
    {
      "id": "device-uuid-2",
      "name": "Office Hub",
      "isOnline": false
    }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "limit": 10,
    "totalPages": 3
  }
}

Error Responses

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "email",
      "message": "email must be a valid email address"
    }
  ]
}

HTTP Status Codes

Success Codes

Status	Description	When Used
200 OK	Request succeeded	GET, PUT, PATCH
201 Created	Resource created	POST
204 No Content	Request succeeded, no body	DELETE

Client Error Codes

Status	Description	Example
400 Bad Request	Invalid request	Missing required field
401 Unauthorized	Authentication required	Invalid/missing token
403 Forbidden	Access denied	Insufficient permissions
404 Not Found	Resource not found	Invalid ID
409 Conflict	Resource conflict	Duplicate email
422 Unprocessable	Validation error	Invalid data format
429 Too Many Requests	Rate limited	Exceeded rate limit

Server Error Codes

Status	Description	Action
500 Internal Server Error	Server error	Report issue
502 Bad Gateway	Upstream error	Retry later
503 Service Unavailable	Maintenance	Retry later
504 Gateway Timeout	Timeout	Retry with longer timeout

Pagination

Request

GET /api/v1/devices?page=2&limit=20

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number (1-indexed)
limit	number	20	Items per page (max 100)
sort	string	createdAt	Sort field
order	string	desc	Sort order (asc or desc)

Response

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 2,
    "limit": 20,
    "totalPages": 8
  }
}

Meta Object

Field	Type	Description
total	number	Total items across all pages
page	number	Current page number
limit	number	Items per page
totalPages	number	Total number of pages

Filtering

Single Value

GET /api/v1/devices?isOnline=true

Multiple Values

GET /api/v1/devices?status=active,pending

Date Range

GET /api/v1/devices?createdAfter=2024-01-01&createdBefore=2024-12-31

Timestamps

All timestamps are in ISO 8601 format (UTC):

{
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T14:45:30.123Z",
  "lastSeenAt": "2024-01-15T14:50:00.000Z"
}

UUIDs

All IDs are UUIDs (v4):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "deviceId": "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
}

Nullable Fields

Fields that may be null are clearly indicated:

{
  "id": "device-uuid",
  "name": "Home Hub",
  "ipAddress": "192.168.1.100",
  "lastSeenAt": null,
  "metadata": null
}

Nested Resources

Related resources may be included:

Expanded Response

{
  "id": "device-uuid",
  "name": "Home Hub",
  "users": [
    {
      "id": "user-uuid",
      "email": "owner@example.com",
      "role": "owner"
    }
  ]
}

Reference Only

{
  "id": "device-user-uuid",
  "userId": "user-uuid",
  "deviceId": "device-uuid",
  "role": "editor"
}

Authentication Responses

Login Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 900,
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "user"
  }
}

Token Response Fields

Field	Type	Description
accessToken	string	JWT access token
refreshToken	string	JWT refresh token
expiresIn	number	Access token lifetime in seconds
user	object	User profile (on login only)

Rate Limit Headers

All responses include rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1700000060

Content Types

Request

Content-Type: application/json

Response

Content-Type: application/json; charset=utf-8

CORS Headers

Access-Control-Allow-Origin: https://app.asahome.io
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Credentials: true

Example Responses

GET /devices

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "uuid": "device-uuid-1",
      "deviceId": "asahome-home-001",
      "name": "Home Hub",
      "isOnline": true,
      "lastSeenAt": "2024-01-15T14:50:00.000Z",
      "role": "owner"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

POST /devices/register

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "uuid": "device-uuid-new",
  "deviceId": "asahome-home-002",
  "name": "Office Hub",
  "ipAddress": "192.168.1.101",
  "port": "8123",
  "isOnline": false,
  "metadata": null,
  "createdAt": "2024-01-15T15:00:00.000Z",
  "updatedAt": "2024-01-15T15:00:00.000Z"
}

Error: Validation Failed

{
  "statusCode": 400,
  "message": [
    "uuid must be a UUID",
    "name should not be empty"
  ],
  "error": "Bad Request"
}

Error: Unauthorized

{
  "statusCode": 401,
  "message": "Token has expired",
  "error": "Unauthorized"
}

Error: Not Found

{
  "statusCode": 404,
  "message": "Device not found",
  "error": "Not Found"
}

Response Headers Reference

Header	Description
Content-Type	Response content type
X-RateLimit-Limit	Rate limit ceiling
X-RateLimit-Remaining	Remaining requests
X-RateLimit-Reset	Reset timestamp
X-Request-Id	Unique request identifier