Overview

Nodit Powerful APIs Overview

Nodit의 강력한 Web3 Data API와 인덱싱 데이터 등을 활용하여 이더리움, 폴리곤과 같은 Public 블록체인을 빠르고 쉽게 연동할 수 있습니다. Web3 제품 개발을 위한 다양한 API 들을 살펴보고 바로 적용해보세요.


Web3 Data API

Nodit은 다양한 Public 체인의 Data를 유저가 쉽고 편리하게 연동하여 사용할 수 있도록 다양한 API를 제공하고 있습니다. Nodit에서 Web3 Data API를 이용할 수 있는 환경은 다음과 같습니다.

Supported ProtocolSupported Network
The BalanceMainnet
EthereumMainnet
Sepolia
Holesky
PolygonMainnet
Amoy
OptimismMainnet
Sepolia
ArbitrumMainnet
Sepolia
BaseMainnet
Sepolia

아래 링크를 클릭하여 Web3 Data API를 이용해 보세요!

Nodit Web3 Data API 확인하기


API Design

1. Path

Nodit Web3 Data API의 Path는 공통적으로 아래와 같이 구성됩니다.

/{version}/{protocol}/{network}/{API resource}
//EXAMPLE: /v1/ethereum/mainnet/accounts
  • version: API의 버전을 명시합니다. (예시) v1
  • protocol: 호출 대상 블록체인 환경의 프로토콜을 명시합니다.
  • network: 호출 대상 블록체인 환경의 네트워크를 명시합니다.
  • resource: 각 API의 리소스가 정의되는 파트로, 계층 구조로 구성됩니다.

2. Listing & Paging

API의 응답이 목록 형식의 데이터를 포함하는 경우 아래와 같이 countitems항목을 활용하여 목록의 크기와 데이터를 구분하여 정의합니다. 또한 대부분의 목록 응답에 대해서는 Paging을 위한 Query Parameter 사용을 지원합니다. 자세한 파라미터 사용법에 대해서는 아래 테이블을 참고하세요.

PropertyTypeDescriptionExample Value
countInteger전체 아이템의 개수.20
itemsarray:object응답 객체의 배열(목록).
pageInteger목록 Pagination을 위한 페이지 번호. 특정 페이지부터의 결과 조회를 위한 Query Parameter로 지원되며, 1 이상 100 이하의 정수형 타입을 지원합니다. 지원하지 않는 형식이 입력되는 경우엔 무시합니다. 기본값은 1입니다.1
rppInteger목록 Pagination 시 Page당 조회할 결과 아이템의 수. 1 이상 100 미만의 정수형 타입을 지원합니다. 기본값은 20입니다.20
cursorstringcursor 파라미터는 Pagination 위해 사용되며, 이전 페이지와 다음 페이지 간의 데이터 이동을 지원합니다. 이전 페이지에서 얻은 cursor 값을 다음 요청에 제공하면 다음 페이지의 데이터를 로드할 수 있습니다. page와 cursor를 모두 입력하지 않는 경우에는, cursor Pagination을 사용하는 것으로 간주합니다. 이 파라미터는 page 파라미터와 동시에 사용할 수 없습니다.

3. Response Format

모든 Nodit Web3 Data API의 응답은 Object 내에 Data를 포함하는 형태이며 응답이 단건이 아닌 Nodit Web3 Data API의 응답은 pagination 필드를 포함합니다.

KeyValue Description
pagination응답 2. Listing & Paging에 포함된 값으로 응답의 크기와 데이터를 구분하는 값.
포함되는 Field는 count, items, page, rpp, cursor 가 있습니다.

정상 응답(HTTP 상태코드가 2XX인 경우)의 경우 응답 Body 내부에 실제 응답 객체가 도메인 응답의 형태로 반환됩니다.

KeyValue Description
data요청에 대한 결과 응답 data 객체.

정상 응답이 아닌 경우, message필드가 code필드와 함께 응답 내에 포함됩니다. 발생한 오류에 대한 설명을 포함합니다.

KeyValue 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

오류가 발생한 경우 응답은 아래와 같은 형식으로 반환됩니다. codemessage는 발생한 에러 타입에 따라 다른 값으로 반환되며, code 명세에 대해서는 아래 Error Code Specification을 참고하세요.

{
   "code":"${CODE}",
   "message":"${ERROR_DESCRIPTION}"
}

Error Code Specification

codeHTTP Status CodeDescription
SUCCESS200 OK정상 응답
SUCCESS201 Created정상 처리 (신규 생성)
MISSING_REQUIRED_PARAMETER400 Bad Request필수 인자가 누락된 경우.

[Example Cases]

1. Path, Query, 또는 Body parameter 중 필수 필드 누락
INVALID_PARAMETER400 Bad Request인자에 잘못된 값을 입력한 경우.

[Example Casess]

1. 지정된 인자의 형식과 위배되는 값이 입력된 경우
2. 인자에 빈 값을 전달한 경우
3. 허용되는 최대 길이를 초과하는 값을 전달한 경우
4. 유효하지 않은 날짜/시간 형식을 입력된 경우
5. 정의된 인코딩 스킴을 적용하지 않은 인자가 입력된 경우
6. 포맷에 맞지 않는 인자 값을 입력한 경우
7. 호환되지 않는 파라미터를 함께 사용한 경우
WRONG_RANGE_PARAMETER400 Bad Request조회 범위를 지정하는 인자에 범위 밖의 값을 입력한 경우.

[Example Cases]

1. 통계 API에서 최대 조회 일자를 초과하여 요청한 경우
2. 기준일 이전 데이터를 요청한 경우
3. 존재하지 않는 데이터 범위에 대해 요청한 경우
DEPRECATED_OPERATION400 Bad RequestDeprecate된 API 및 리소스에 대한 요청한 경우.

[Example Cases]

1. API 버전이 업데이트되어 더이상 지원하지 않는 이전 버전의 API를 요청한 경우
NO_AUTHENTICATION_FOUND401 Unauthorized요청 내 인증 정보가 존재하나, 정보의 불일치 또는 존재하지 않는 계정 정보 에러

[Example Cases]

1. path 또는 header에 인증 정보가 포함되었으나 유효기간이 지난 경우
2. path 또는 header에 인증 정보가 포함되었으나 다른 계정의 인증 정보를 사용한 경우
AUTHENTICATION_FAILED401 Unauthorized요청 내 인증 정보 포함되지 않는 경우에 대한 에러

[Example Cases]

1. path 혹은 header에 인증 정보를 입력하지 않은 경우
PERMISSION_DENIED403 Forbidden인증은 완료되었으나 인가되지 않은 리소스에 접근하는 경우 권한 에러

[Example Cases]

1. 인증 정보의 권한이 없는 요청을 진행한 경우
WRONG_ENDPOINT404 Not Found요청한 API 경로가 존재하지 않는 경우

[Example Cases]

1. 잘못된 API 경로를 요청한 경우
2. 존재하지 않는 API 버전을 요청한 경우
3. 서버에서 제거되었거나 변경된 API를 호출한 경우
NOT_SUPPORTED_CHAIN404 Not Found요청한 체인에서 지원하지 않는 서비스 경로를 요청한 경우

[Example Cases]

1. 해당 path의 기능에서 path parameter의 {protocol}필드에 지정된 체인을 서비스하지 않는 경우
RESOURCE_NOT_FOUND404 Not Found요청한 리소스가 서버에 존재하지 않는 경우

[Example Cases]

1. 서버에 없는 데이터를 요청한 경우
2. 존재하지 않는 파일이나 리소스에 대한 요청
3. 유효하지 않은 ID나 키를 사용하여 데이터를 요청한 경우
METHOD_NOT_ALLOWED405 Method Not Allowed허용되지 않는 HTTP 메서드로 요청한 경우

[Example Cases]

1. 유효한 HTTP 메서드 타입이지만 요청한 API에서는 지원하지 않는 경우
2. 유효하지 않은 HTTP 메서드 타입으로 요청한 경우
TIMEOUT408 Request Timeout호출이 정해진 시간 이내에 완료되지 않는 경우 혹은 WAS 컨트롤러에서 목표로 한 시간 제한을 초과한 경우

[Example Cases]

1. Transaction receipt 조회를 위한 체인에 대한 RPC 호출이 5초 이내에 완료되지 않은 경우, 재시도 3회 포함 모두 실패 시 클라이언트에게 최종 TIMEOUT 에러 반환함.
2. Elasticsearch 서비스 호출시, receipt 조회 응답이 5초 내에 완료되지 않은 경우
RESOURCE_ALREADY_EXISTS409 Conflict이미 존재하는 리소스에 대한 중복 생성 요청한 경우

[Example Cases]

1. 중복 생성될 수 없는 리소스에 대한 중복 생성 시도
2. 요청된 식별 값을 키 값으로 생성 요청시, 해당 식별 값이 이미 존재하는 경우
REJECTED409 Conflict요청 처리가 서버로부터 거절된 경우
CONTENTS_TOO_LARGE413 Payload Too Large서버에서 설정된 payload 최대값을 초과한 경우
TOO_LONG_URI414 URI Too Long클라이언트 요청이 서버에서 해석가능한 최대 URI 길이를 초과한 경우 반환되는 에러.
TOO_MANY_REQUESTS429 Too Many Request허용된 Rate limit을 초과하는 경우

[Example Cases]

1. 초당/분당 Compute Unit 제한이 있는 경우
2. 초당/분당 Bytes 사이즈 제한이 있는 경우
3. 초당/분당 Requests 제한이 있는 경우
EXCEEDED_QUOTA_LIMIT429 Too many request허용된 Quota limit을 초과한 경우

[Example Cases]

1. 사용자의 요금제에서 제공하는 월별 사용량을 초과한 경우
INTERNAL_SERVER_ERROR500 Internal Server Error내부 서버 오류

[Example Cases]

1. 처리되지 않는 런타임 에러가 발생하는 경우
2. 인프라(DB, 스토리지, 큐, 캐시 등) 및 외부 서비스 호출과 같은 도메인 컨텍스트 이외의 영역에서 발생하는 모든 내부 에러의 경우
INTERRUPTED500 Internal Server Error다중 요청을 처리하는 과정에서 특정 클라이언트의 요청에 대해 일시적으로 처리가 실패한 경우.

서버 부하로 인한 에러로 판단 할 수 있음.
UNAVAILABLE503 Service Unavailable서버의 서비스 제공이 불가능한 상태. 인프라의 다운 또는 서비스 중단을 동반한 업그레이드 작업 등으로 인해 반환될 수 있는 에러.

JSON-RPC Error Code Specification

CodeMessageDescription
-32000server error빈 배치에 대한 오류 응답으로 반환될 수 있는 에러
-32001notifications not supported알림이 지원되지 않을 때 반환될 수 있는 에러
-32002request timed outtime out이 발생했을 때 반횐될 수 있는 에러
-32600invalid request유효한 요청이 아닐 경우, 혹은 jsonrpc batch request 안에 eth_subscribe, eth_unsubscribe method를 포함한 경우 반환 될 수 있는 에러
-32601"the method X does not exist/is not available”존재 하지 않는 method를 호출 했을 경우 반환될 수 있는 에러
-32601subscription not found존재하지 않는 subscription을 호출 했을 경우 반환될 수 있는 에러
-32602Invalid parameter
("missing value for required argument X”)
입력한 Parameters가 디코딩할 수 없거나 입력한 Parameters 수가 잘못되었을 때 반환될 수 있는 에러.
-32603Internal errorInternal JSON-RPC 에러
-32700parse error서버로 부터 Invalid된 JSON을 받았을 경우 반환될 수 있는 에러