# 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

| ✅ Good Examples               | ❌ Bad Examples               |
|--------------------------------|------------------------------|
| GET /transactions              | GET /get-all-transactions    |
| GET /users/{userId}/portfolios | GET /userPortfolio           |
| GET /smart-contracts/events    | GET /smart\_contract\_events |

### 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:

```json
{
  "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
```