Introduction & Standards

Overview

Our API serves as the primary interface between the frontend application and the blockchain infrastructure. It provides a RESTful interface that handles business logic, smart contract interactions, and data management.

API Design Principles

1. RESTful Resource Naming

• Use nouns for resource names
• Apply consistent plural forms for collections
• Use kebab-case for URLs
• Nest resources logically

2. HTTP Methods

Use standard HTTP methods consistently:

• GET: Retrieve resources
• POST: Create new resources
• PUT: Update existing resources (full update)
• PATCH: Partial resource updates
• DELETE: Remove resources

3. Response Formats

All API responses follow this standard structure:

{
  "status": "success" | "error",
  "data": {
    // Response payload
  },
  "metadata": {
    "timestamp": "ISO-8601 timestamp",
    "version": "API version",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100
    }
  },
  "errors": [
    {
      "code": "ERROR_CODE",
      "message": "Human readable message",
      "field": "field_name"
    }
  ]
}

4. Status Codes

Code	Description	Usage
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Invalid input
401	Unauthorized	Missing/invalid authentication
403	Forbidden	Authenticated but unauthorized
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

5. Versioning

• Version prefix in URL: /v1/resources
• Major version changes only
• Maintain backwards compatibility within versions
• Support at most 2 versions simultaneously

6. Query Parameters

Pagination

Filtering

Sorting