# REST API Specification

## Overview

This document specifies the REST API for the explorer platform. The API follows RESTful principles and provides comprehensive access to blockchain data, search, and analytics.

**Base URL**: `https://api.explorer.d-bis.org/v1`

**Authentication**: API Key via `X-API-Key` header (optional for read-only endpoints with rate limits)

## API Design Principles

1. **RESTful**: Use HTTP methods appropriately (GET, POST, etc.)
2. **Consistent**: Uniform response format
3. **Versioned**: `/v1` in path, version in response headers
4. **Paginated**: All list endpoints support pagination
5. **Filtered**: Support filtering and sorting
6. **Documented**: OpenAPI 3.0 specification

## Response Format

### Success Response

```json
{
  "data": { ... },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 100,
      "total_pages": 5
    }
  }
}
```

### Error Response

```json
{
  "error": {
    "code": "not_found",
    "message": "Resource not found",
    "details": {},
    "request_id": "uuid"
  }
}
```

## Endpoints

### Blocks

#### List Blocks

`GET /blocks`

**Query Parameters**:
- `chain_id` (integer, required): Chain ID
- `page` (integer, default: 1): Page number
- `page_size` (integer, default: 20, max: 100): Items per page
- `min_block` (integer): Minimum block number
- `max_block` (integer): Maximum block number
- `miner` (string): Filter by miner address
- `sort` (string, default: "number"): Sort field (number, timestamp, gas_used)
- `order` (string, default: "desc"): Sort order (asc, desc)

**Response**:
```json
{
  "data": [
    {
      "chain_id": 138,
      "number": 12345,
      "hash": "0x...",
      "timestamp": "2024-01-01T00:00:00Z",
      "miner": "0x...",
      "transaction_count": 100,
      "gas_used": 15000000,
      "gas_limit": 20000000
    }
  ],
  "meta": { "pagination": {...} }
}
```

#### Get Block by Number

`GET /blocks/{chain_id}/{number}`

**Response**: Single block object

#### Get Block by Hash

`GET /blocks/{chain_id}/hash/{hash}`

**Response**: Single block object

### Transactions

#### List Transactions

`GET /transactions`

**Query Parameters**:
- `chain_id` (integer, required)
- `block_number` (integer): Filter by block
- `from_address` (string): Filter by sender
- `to_address` (string): Filter by recipient
- `status` (string): Filter by status (success, failed)
- `min_value` (string): Minimum value
- `page`, `page_size`, `sort`, `order`

**Response**: Array of transaction objects

#### Get Transaction by Hash

`GET /transactions/{chain_id}/{hash}`

**Response**: Single transaction object with full details

**Includes**:
- Transaction data
- Receipt data
- Logs
- Traces (if available)

#### Get Transaction Receipt

`GET /transactions/{chain_id}/{hash}/receipt`

**Response**: Transaction receipt object

### Addresses

#### Get Address Info

`GET /addresses/{chain_id}/{address}`

**Response**:
```json
{
  "address": "0x...",
  "chain_id": 138,
  "balance": "1000000000000000000",
  "balance_usd": "3000.00",
  "transaction_count": 500,
  "token_count": 10,
  "label": "My Wallet",
  "tags": ["wallet"],
  "is_contract": false
}
```

#### Get Address Transactions

`GET /addresses/{chain_id}/{address}/transactions`

**Query Parameters**: Standard pagination and filtering

**Response**: Array of transactions

#### Get Address Token Holdings

`GET /addresses/{chain_id}/{address}/tokens`

**Query Parameters**:
- `type` (string): Filter by token type (ERC20, ERC721, ERC1155)
- `page`, `page_size`

**Response**: Array of token holdings with balances

#### Get Address NFTs

`GET /addresses/{chain_id}/{address}/nfts`

**Response**: Array of NFT holdings (ERC-721/1155)

### Tokens

#### List Tokens

`GET /tokens`

**Query Parameters**:
- `chain_id` (integer, required)
- `type` (string): Filter by type
- `verified` (boolean): Filter verified tokens
- `search` (string): Search by name or symbol
- `page`, `page_size`, `sort`, `order`

**Response**: Array of token objects

#### Get Token Info

`GET /tokens/{chain_id}/{address}`

**Response**: Token details including metadata

#### Get Token Holders

`GET /tokens/{chain_id}/{address}/holders`

**Query Parameters**: Pagination

**Response**: Array of holder addresses with balances

#### Get Token Transfers

`GET /tokens/{chain_id}/{address}/transfers`

**Query Parameters**: Pagination, `from_address`, `to_address`

**Response**: Array of token transfers

### Contracts

#### Get Contract Info

`GET /contracts/{chain_id}/{address}`

**Response**: Contract details including verification status, source code, ABI

#### Verify Contract

`POST /contracts/{chain_id}/{address}/verify`

**Request Body**:
```json
{
  "compiler_version": "0.8.19",
  "optimization_enabled": true,
  "optimization_runs": 200,
  "source_code": "...",
  "constructor_arguments": "0x...",
  "verification_method": "standard_json"
}
```

**Response**: Verification status

#### Get Contract Source Code

`GET /contracts/{chain_id}/{address}/source`

**Response**: Source code and metadata

#### Get Contract ABI

`GET /contracts/{chain_id}/{address}/abi`

**Response**: Contract ABI JSON

### Logs

#### Get Logs

`GET /logs`

**Query Parameters**:
- `chain_id` (integer, required)
- `address` (string): Filter by contract address
- `topic0` (string): Filter by event signature
- `from_block` (integer): Start block
- `to_block` (integer): End block
- `page`, `page_size`

**Response**: Array of log objects

### Traces

#### Get Transaction Traces

`GET /transactions/{chain_id}/{hash}/traces`

**Response**: Array of trace objects

#### Get Block Traces

`GET /blocks/{chain_id}/{number}/traces`

**Response**: Array of trace objects for all transactions in block

### Search

#### Unified Search

`GET /search`

**Query Parameters**:
- `chain_id` (integer, optional): Filter by chain
- `q` (string, required): Search query
- `type` (string): Filter by type (block, transaction, address, token, contract)
- `page`, `page_size`

**Response**: Mixed array of results with type indicators

### Analytics

#### Network Stats

`GET /analytics/{chain_id}/network/stats`

**Response**:
```json
{
  "current_block": 12345,
  "tps": 15.5,
  "gps": 30000000,
  "avg_gas_price": 20000000000,
  "pending_transactions": 50
}
```

#### Gas Price Statistics

`GET /analytics/{chain_id}/gas/price`

**Query Parameters**:
- `period` (string): Time period (1h, 24h, 7d, 30d)

**Response**: Gas price statistics (min, max, avg, percentiles)

#### Top Contracts

`GET /analytics/{chain_id}/contracts/top`

**Query Parameters**:
- `by` (string): Sort by (transactions, gas_used, value)
- `limit` (integer, default: 100)

**Response**: Array of top contracts

## Pagination

All list endpoints support pagination:

**Query Parameters**:
- `page` (integer, default: 1): Page number (1-indexed)
- `page_size` (integer, default: 20, max: 100): Items per page

**Response Metadata**:
```json
{
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 500,
      "total_pages": 25,
      "has_next": true,
      "has_prev": false
    }
  }
}
```

## Filtering and Sorting

**Common Filter Parameters**:
- Date ranges: `from_date`, `to_date`
- Block ranges: `from_block`, `to_block`
- Value ranges: `min_value`, `max_value`
- Address filters: `from_address`, `to_address`

**Sorting**:
- `sort` (string): Field to sort by
- `order` (string): `asc` or `desc`

## Rate Limiting

See API Gateway specification for rate limiting details.

**Rate Limit Headers**:
- `X-RateLimit-Limit`: Request limit
- `X-RateLimit-Remaining`: Remaining requests
- `X-RateLimit-Reset`: Reset timestamp

## OpenAPI Specification

Full OpenAPI 3.0 specification available at:
- `/api-docs/openapi.json`
- Interactive docs: `/api-docs` (Swagger UI)

## Versioning

**Current Version**: v1

**Version Header**: `API-Version: 1`

**Deprecation**: Deprecated endpoints return `Deprecation` header with deprecation date

## References

- API Gateway: See `api-gateway.md`
- GraphQL API: See `graphql-api.md`
- Etherscan-Compatible API: See `etherscan-compatible-api.md`