Nodit Powerful APIs Overview
Nodit의 강력한 Web3 Data API와 인덱싱 데이터 등을 활용하여 이더리움, 폴리곤과 같은 Public 블록체인을 빠르고 쉽게 연동할 수 있습니다. Web3 제품 개발을 위한 다양한 API 들을 살펴보고 바로 적용해보세요.
Web3 Data API
Nodit은 다양한 Public 체인의 Data를 유저가 쉽고 편리하게 연동하여 사용할 수 있도록 다양한 API를 제공하고 있습니다. Nodit에서 Web3 Data API를 이용할 수 있는 환경은 다음과 같습니다.
Supported Protocol | Supported Network |
---|---|
The Balance | Mainnet |
Ethereum | Mainnet |
Sepolia | |
Holesky | |
Polygon | Mainnet |
Amoy | |
Optimism | Mainnet |
Sepolia | |
Arbitrum | Mainnet |
Sepolia | |
Base | Mainnet |
Sepolia |
아래 링크를 클릭하여 Web3 Data API를 이용해 보세요!
API Design
1. Path
Nodit Web3 Data API의 Path는 공통적으로 아래와 같이 구성됩니다.
/{version}/{protocol}/{network}/{API resource}
//EXAMPLE: /v1/ethereum/mainnet/accounts
version
: API의 버전을 명시합니다. (예시) v1protocol
: 호출 대상 블록체인 환경의 프로토콜을 명시합니다.network
: 호출 대상 블록체인 환경의 네트워크를 명시합니다.resource
: 각 API의 리소스가 정의되는 파트로, 계층 구조로 구성됩니다.
2. Listing & Paging
API의 응답이 목록 형식의 데이터를 포함하는 경우 아래와 같이 count
와 items
항목을 활용하여 목록의 크기와 데이터를 구분하여 정의합니다. 또한 대부분의 목록 응답에 대해서는 Paging을 위한 Query Parameter 사용을 지원합니다. 자세한 파라미터 사용법에 대해서는 아래 테이블을 참고하세요.
Property | Type | Description | Example Value |
---|---|---|---|
count | Integer | 전체 아이템의 개수. | 20 |
items | array:object | 응답 객체의 배열(목록). | |
page | Integer | 목록 Pagination을 위한 페이지 번호. 특정 페이지부터의 결과 조회를 위한 Query Parameter로 지원되며, 1 이상 100 이하의 정수형 타입을 지원합니다. 지원하지 않는 형식이 입력되는 경우엔 무시합니다. 기본값은 1입니다. | 1 |
rpp | Integer | 목록 Pagination 시 Page당 조회할 결과 아이템의 수. 1 이상 100 미만의 정수형 타입을 지원합니다. 기본값은 20입니다. | 20 |
cursor | string | cursor 파라미터는 Pagination 위해 사용되며, 이전 페이지와 다음 페이지 간의 데이터 이동을 지원합니다. 이전 페이지에서 얻은 cursor 값을 다음 요청에 제공하면 다음 페이지의 데이터를 로드할 수 있습니다. page와 cursor를 모두 입력하지 않는 경우에는, cursor Pagination을 사용하는 것으로 간주합니다. 이 파라미터는 page 파라미터와 동시에 사용할 수 없습니다. |
3. Response Format
모든 Nodit Web3 Data API의 응답은 Object 내에 Data를 포함하는 형태이며 응답이 단건이 아닌 Nodit Web3 Data API의 응답은 pagination
필드를 포함합니다.
Key | Value Description |
---|---|
pagination | 응답 2. Listing & Paging에 포함된 값으로 응답의 크기와 데이터를 구분하는 값. 포함되는 Field는 count , items , page , rpp , cursor 가 있습니다. |
정상 응답(HTTP 상태코드가 2XX인 경우)의 경우 응답 Body 내부에 실제 응답 객체가 도메인 응답의 형태로 반환됩니다.
Key | Value Description |
---|---|
data | 요청에 대한 결과 응답 data 객체. |
정상 응답이 아닌 경우, message
필드가 code
필드와 함께 응답 내에 포함됩니다. 발생한 오류에 대한 설명을 포함합니다.
Key | Value Description |
---|---|
message | 오류에 대한 설명 메세지. |
성공과 실패 각 케이스에 대한 응답 예시는 다음과 같습니다.
// Successful response with 2XX http status code (single record)
{
requested domain response will be included here
}
// Successful response with 2XX http status code (mutiful record)
{
"count": int,
"cursor": "string", // or "page": 1
"rpp": int,
"items": [
{
requested domain response will be included here
}
]
}
// Error response
{
"code":"RESOURCE_NOT_FOUND",
"message":"The error message will be include here"
}
4. Error Response Format
오류가 발생한 경우 응답은 아래와 같은 형식으로 반환됩니다. code
와 message
는 발생한 에러 타입에 따라 다른 값으로 반환되며, code
명세에 대해서는 아래 Error Code Specification을 참고하세요.
{
"code":"${CODE}",
"message":"${ERROR_DESCRIPTION}"
}
Error Code Specification
code | HTTP Status Code | Description |
---|---|---|
SUCCESS | 200 OK | 정상 응답 |
SUCCESS | 201 Created | 정상 처리 (신규 생성) |
MISSING_REQUIRED_PARAMETER | 400 Bad Request | 필수 인자가 누락된 경우. [Example Cases] 1. Path, Query, 또는 Body parameter 중 필수 필드 누락 |
INVALID_PARAMETER | 400 Bad Request | 인자에 잘못된 값을 입력한 경우. [Example Casess] 1. 지정된 인자의 형식과 위배되는 값이 입력된 경우 2. 인자에 빈 값을 전달한 경우 3. 허용되는 최대 길이를 초과하는 값을 전달한 경우 4. 유효하지 않은 날짜/시간 형식을 입력된 경우 5. 정의된 인코딩 스킴을 적용하지 않은 인자가 입력된 경우 6. 포맷에 맞지 않는 인자 값을 입력한 경우 7. 호환되지 않는 파라미터를 함께 사용한 경우 |
WRONG_RANGE_PARAMETER | 400 Bad Request | 조회 범위를 지정하는 인자에 범위 밖의 값을 입력한 경우. [Example Cases] 1. 통계 API에서 최대 조회 일자를 초과하여 요청한 경우 2. 기준일 이전 데이터를 요청한 경우 3. 존재하지 않는 데이터 범위에 대해 요청한 경우 |
DEPRECATED_OPERATION | 400 Bad Request | Deprecate된 API 및 리소스에 대한 요청한 경우. [Example Cases] 1. API 버전이 업데이트되어 더이상 지원하지 않는 이전 버전의 API를 요청한 경우 |
NO_AUTHENTICATION_FOUND | 401 Unauthorized | 요청 내 인증 정보가 존재하나, 정보의 불일치 또는 존재하지 않는 계정 정보 에러 [Example Cases] 1. path 또는 header에 인증 정보가 포함되었으나 유효기간이 지난 경우 2. path 또는 header에 인증 정보가 포함되었으나 다른 계정의 인증 정보를 사용한 경우 |
AUTHENTICATION_FAILED | 401 Unauthorized | 요청 내 인증 정보 포함되지 않는 경우에 대한 에러 [Example Cases] 1. path 혹은 header에 인증 정보를 입력하지 않은 경우 |
PERMISSION_DENIED | 403 Forbidden | 인증은 완료되었으나 인가되지 않은 리소스에 접근하는 경우 권한 에러 [Example Cases] 1. 인증 정보의 권한이 없는 요청을 진행한 경우 |
WRONG_ENDPOINT | 404 Not Found | 요청한 API 경로가 존재하지 않는 경우 [Example Cases] 1. 잘못된 API 경로를 요청한 경우 2. 존재하지 않는 API 버전을 요청한 경우 3. 서버에서 제거되었거나 변경된 API를 호출한 경우 |
NOT_SUPPORTED_CHAIN | 404 Not Found | 요청한 체인에서 지원하지 않는 서비스 경로를 요청한 경우 [Example Cases] 1. 해당 path의 기능에서 path parameter의 {protocol}필드에 지정된 체인을 서비스하지 않는 경우 |
RESOURCE_NOT_FOUND | 404 Not Found | 요청한 리소스가 서버에 존재하지 않는 경우 [Example Cases] 1. 서버에 없는 데이터를 요청한 경우 2. 존재하지 않는 파일이나 리소스에 대한 요청 3. 유효하지 않은 ID나 키를 사용하여 데이터를 요청한 경우 |
METHOD_NOT_ALLOWED | 405 Method Not Allowed | 허용되지 않는 HTTP 메서드로 요청한 경우 [Example Cases] 1. 유효한 HTTP 메서드 타입이지만 요청한 API에서는 지원하지 않는 경우 2. 유효하지 않은 HTTP 메서드 타입으로 요청한 경우 |
TIMEOUT | 408 Request Timeout | 호출이 정해진 시간 이내에 완료되지 않는 경우 혹은 WAS 컨트롤러에서 목표로 한 시간 제한을 초과한 경우 [Example Cases] 1. Transaction receipt 조회를 위한 체인에 대한 RPC 호출이 5초 이내에 완료되지 않은 경우, 재시도 3회 포함 모두 실패 시 클라이언트에게 최종 TIMEOUT 에러 반환함. 2. Elasticsearch 서비스 호출시, receipt 조회 응답이 5초 내에 완료되지 않은 경우 |
RESOURCE_ALREADY_EXISTS | 409 Conflict | 이미 존재하는 리소스에 대한 중복 생성 요청한 경우 [Example Cases] 1. 중복 생성될 수 없는 리소스에 대한 중복 생성 시도 2. 요청된 식별 값을 키 값으로 생성 요청시, 해당 식별 값이 이미 존재하는 경우 |
REJECTED | 409 Conflict | 요청 처리가 서버로부터 거절된 경우 |
CONTENTS_TOO_LARGE | 413 Payload Too Large | 서버에서 설정된 payload 최대값을 초과한 경우 |
TOO_LONG_URI | 414 URI Too Long | 클라이언트 요청이 서버에서 해석가능한 최대 URI 길이를 초과한 경우 반환되는 에러. |
TOO_MANY_REQUESTS | 429 Too Many Request | 허용된 Rate limit을 초과하는 경우 [Example Cases] 1. 초당/분당 Compute Unit 제한이 있는 경우 2. 초당/분당 Bytes 사이즈 제한이 있는 경우 3. 초당/분당 Requests 제한이 있는 경우 |
EXCEEDED_QUOTA_LIMIT | 429 Too many request | 허용된 Quota limit을 초과한 경우 [Example Cases] 1. 사용자의 요금제에서 제공하는 월별 사용량을 초과한 경우 |
INTERNAL_SERVER_ERROR | 500 Internal Server Error | 내부 서버 오류 [Example Cases] 1. 처리되지 않는 런타임 에러가 발생하는 경우 2. 인프라(DB, 스토리지, 큐, 캐시 등) 및 외부 서비스 호출과 같은 도메인 컨텍스트 이외의 영역에서 발생하는 모든 내부 에러의 경우 |
INTERRUPTED | 500 Internal Server Error | 다중 요청을 처리하는 과정에서 특정 클라이언트의 요청에 대해 일시적으로 처리가 실패한 경우. 서버 부하로 인한 에러로 판단 할 수 있음. |
UNAVAILABLE | 503 Service Unavailable | 서버의 서비스 제공이 불가능한 상태. 인프라의 다운 또는 서비스 중단을 동반한 업그레이드 작업 등으로 인해 반환될 수 있는 에러. |
JSON-RPC Error Code Specification
Code | Message | Description |
---|---|---|
-32000 | server error | 빈 배치에 대한 오류 응답으로 반환될 수 있는 에러 |
-32001 | notifications not supported | 알림이 지원되지 않을 때 반환될 수 있는 에러 |
-32002 | request timed out | time out이 발생했을 때 반횐될 수 있는 에러 |
-32600 | invalid request | 유효한 요청이 아닐 경우, 혹은 jsonrpc batch request 안에 eth_subscribe, eth_unsubscribe method를 포함한 경우 반환 될 수 있는 에러 |
-32601 | "the method X does not exist/is not available” | 존재 하지 않는 method를 호출 했을 경우 반환될 수 있는 에러 |
-32601 | subscription not found | 존재하지 않는 subscription을 호출 했을 경우 반환될 수 있는 에러 |
-32602 | Invalid parameter ("missing value for required argument X”) | 입력한 Parameters가 디코딩할 수 없거나 입력한 Parameters 수가 잘못되었을 때 반환될 수 있는 에러. |
-32603 | Internal error | Internal JSON-RPC 에러 |
-32700 | parse error | 서버로 부터 Invalid된 JSON을 받았을 경우 반환될 수 있는 에러 |