Metadata

Metadata plays a crucial role in providing clear and comprehensive information about the API endpoints, data formats, and other essential details.

General description of the metadata

Endpoint Description

Request Parameters

Request Payload

Response Structure

Authentication and Authorization

Rate Limiting

Error Handling

Versioning

Security Considerations

Endpoint Description

Clearly state each API endpoint's purpose and functionality. Include information about the HTTP methods (GET, POST, PUT, DELETE) supported by each endpoint.

Request Parameters

List all parameters that can be included in the request (query parameters, path parameters, headers, etc.). Describe each parameter's type (string, number, boolean, etc.), format (date, timestamp, etc.), and whether it's required or optional.

Request Payload

If applicable (for POST, PUT requests), describe the structure and format of the request body (JSON, XML, etc.). Provide examples of valid payloads.

Response Structure

Describe the structure of the response returned by the API. Include details about response codes (success, error), data formats (JSON, XML), and any specific fields included in the response.

💡 Status Codes:

200 OK: The request was successful, and the device status is returned.

404 Not Found: The specified device ID does not exist.

500 Internal Server Error: An error occurred on the server.

Response Body Example:

{
  "deviceId": "12345",
  "status": "online",
  "temperature": 72.5,
  "batteryLevel": 85
}

Error Responses Example:

📌

Status Code: 404 Not Found

{
  "error": "Device not found",
  "message": "The device with the specified ID does not exist."
}

📌

Status Code: 401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid API token provided."
}

Authentication and Authorization

Authentication

Use HTTPS
Always use HTTPS to encrypt data in transit and protect against eavesdropping and man-in-the-middle attacks.

API Tokens
Authenticate requests using bearer tokens. Obtain tokens securely and avoid exposing them in client-side code or logs.

Authentication Method

This API uses Bearer Token authentication. Each request to the API must include an Authorization header with a valid token.

📌 Example

{
  "accessToken": "your_access_token_here",
  "expiresIn": 3600  
}

Rate Limiting

To ensure fair usage and prevent abuse, the API enforces rate limits on the number of requests a client can make within a given time period.

Rate Limit Policy

Standard Rate Limit: 1000 requests per hour per API key.

Burst Limit: 50 requests per minute.

Headers for Rate Limit Information

Rate limit information is provided in the response headers of each API request.

Name	Description
X-RateLimit-Limit	The maximum number of requests that the client is allowed to make in the current time period.
X-RateLimit-Remaining	The number of requests remaining in the current time period.
X-RateLimit-Reset	The time at which the current rate limit window resets in UTC epoch seconds.

Example Response Headers:

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1624041600

Error Handling

Document potential error responses that the API might return. Include information about error codes, messages, and how clients should handle these errors.

400 Bad Request

The server could not understand the request due to invalid syntax.

{
  "error": "BadRequest",
  "message": "The request payload is invalid or malformed."
}

401 Unauthorized

The request requires user authentication.

{
  "error": "Unauthorized",
  "message": "Invalid API token provided."
}

403 Forbidden

The server understood the request but refuses to authorize it.

{
  "error": "Forbidden",
  "message": "You do not have permission to access this resource."
}

TIP

Best Practices for Error Handling

Check Status Codes
Always check the HTTP status code of the response to determine if the request was successful.

Parse Error Messages
Parse the JSON error message for more details about the error and how to fix it.

Retry Logic
Implement retry logic with exponential backoff for transient errors such as 500 Internal Server Error or 429 Too Many Requests.

Validation
Validate your request parameters and payloads to minimize 400 Bad Request errors.

Authentication
Ensure that your API token is valid and has the necessary permissions to access the requested resource.

Security Considerations

Ensuring the security and data is critical. The API implements several security measures to protect against unauthorized access and data breaches.

INFO

Link to API documentation - Meta Data API

General description of the metadata#

Endpoint Description#

Request Parameters#

Request Payload#

Response Structure#

Authentication and Authorization#

Authentication#

Authentication Method#

Rate Limiting#

Rate Limit Policy#

Headers for Rate Limit Information#

Error Handling#

400 Bad Request#

401 Unauthorized#

403 Forbidden#

Best Practices for Error Handling#

Security Considerations#

General description of the metadata

Endpoint Description

Request Parameters

Request Payload

Response Structure

Authentication and Authorization

Authentication

Authentication Method

Rate Limiting

Rate Limit Policy

Headers for Rate Limit Information

Error Handling

400 Bad Request

401 Unauthorized

403 Forbidden

Best Practices for Error Handling

Security Considerations