API 일관성

X API v2 전체 엔드포인트에 걸친 일관된 패턴

X API v2는 모든 엔드포인트에서 일관된 패턴을 유지하도록 설계되었습니다. 하나의 엔드포인트 동작 방식을 이해하면 동일한 패턴을 다른 모든 곳에도 적용할 수 있습니다.

---

​

일관된 패턴

​

URL 구조

모든 v2 엔드포인트는 일관된 패턴을 따릅니다.

/version/resource/{id}?parameters
/version/resource/verb?parameters

예시:

/2/tweets/1234567890                    # Get a specific post
/2/tweets/search/recent                 # Search recent posts
/2/users/by/username/xdevelopers        # 사용자 이름으로 사용자 가져오기
/2/users/1234/followers                 # Get user's followers

​

응답 구조

모든 응답에는 동일한 최상위 레벨 구조가 사용됩니다:

{
  "data": { ... },       // 기본 객체
  "includes": { ... },   // 확장된 객체
  "meta": { ... },       // 페이지네이션, 개수
  "errors": [ ... ]      // 부분 오류(있는 경우)
}

​

ID 형식

모든 id는 언어 호환성을 보장하기 위해 문자열로 반환됩니다.

{
  "id": "1234567890123456789",
  "author_id": "2244994945"
}

---

​

필드와 expansions

동일한 fields 및 expansions 매개변수를 일관되게 사용할 수 있습니다:

Object	Fields parameter	Works across
Post	tweet.fields	게시물을 반환하는 모든 엔드포인트
User	user.fields	사용자를 반환하는 모든 엔드포인트
Media	media.fields	media expansions를 사용하는 모든 엔드포인트
Poll	poll.fields	poll expansions를 사용하는 모든 엔드포인트
Place	place.fields	place expansions를 사용하는 모든 엔드포인트

---

​

객체 스키마

동일한 객체 type은 어떤 endpoint에서 반환되더라도 동일한 필드를 가집니다.

• search에서 가져온 게시물은 lookup에서 가져온 게시물과 동일한 필드를 가집니다.
• followers에서 가져온 User는 search에서 가져온 User와 동일한 필드를 가집니다.
• 확장된 객체는 해당 객체를 단독으로 조회했을 때와 동일한 형태입니다.

---

​

인증

모든 엔드포인트에서 다음과 같은 인증 방식을 사용합니다:

방식	헤더 형식
Bearer 토큰	Authorization: Bearer {token}
OAuth 1.0a	Authorization: OAuth {parameters}
OAuth 2.0	Authorization: Bearer {user_token}

---

​

오류 처리

errors 필드는 일관된 형식을 따릅니다:

{
  "title": "Invalid Request",
  "detail": "The query parameter is missing",
  "type": "https://api.x.com/2/problems/invalid-request"
}

모든 오류 유형 보기 →

---

​

페이지네이션

모든 페이지네이션 지원 엔드포인트는 동일한 토큰 시스템을 사용합니다:

Parameter	Description
max_results	페이지당 결과 수
pagination_token	next_token 또는 previous_token에서 받은 토큰

페이지네이션에 대해 더 알아보기 →

---

​

명명 규칙

• 미국식 영어 철자 사용 (favorites, not favourites)
• 필드 이름에는 snake_case 사용 (author_id, created_at)
• 용어 일관성 유지 (필드에서는 repost_count가 아니라 retweet_count 사용)

---

​

빈 값

값이 없는 필드는 null로 반환되지 않고 생략됩니다:

// User without a bio
{
  "id": "1234",
  "name": "Example User",
  "username": "example"
  // "description"은 null이 아니라 생략됨
}

---

​

엔티티 일관성

entities 객체에는 텍스트를 파싱해 추출한 엔티티만 포함합니다:

• urls
• hashtags
• mentions
• cashtags

미디어와 투표는 entities가 아니라 attachments에 있습니다.

---

​

이것이 여러분께 의미하는 것

한 번 배우면 어디서나 활용

한 엔드포인트에서 익힌 패턴을 모든 엔드포인트에 적용할 수 있습니다.

예측 가능한 응답

동일한 객체 type은 API 전체에서 동일한 구조를 가집니다.

더 단순한 코드

공통 패턴을 위한 재사용 가능한 함수를 작성할 수 있습니다.

더 쉬운 디버깅

일관된 오류 형식으로 문제 해결이 더 쉬워집니다.

---

​

불일치 사항 보고

불일치 사항을 발견하셨나요? 아래 채널을 통해 알려 주세요:

• Developer Forum
• Developer Feedback