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:

Method	Description
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

GET /transactions?page=2&limit=20

Filtering

GET /transactions?status=pending&type=deposit

Sorting

GET /transactions?sort=timestamp:desc