400 lines
7.9 KiB
Markdown
400 lines
7.9 KiB
Markdown
# 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`
|
|
|