통합 가이드

이 페이지에는 시스템에 List 조회 엔드포인트를 통합할 때 알아두어야 할 여러 도구와 중요 개념에 대한 정보가 담겨 있습니다. 이 페이지는 다음과 같은 몇 가지 섹션으로 구성되어 있습니다:

• 유용한 도구
• 핵심 개념
• 인증
• 개발자 포털, 프로젝트 및 앱
• 요청 한도
• 필드와 expansions
• 페이지네이션

​

유용한 도구

이 엔드포인트를 통합하는 데 도움이 될 몇 가지 핵심 개념을 살펴보기 전에, 먼저 다음 항목에 익숙해지시길 권장합니다:

​

Postman

Postman은 엔드포인트를 테스트하는 데 유용한 도구입니다. 각 Postman 요청에는 모든 경로 및 본문 매개변수가 포함되어 있어 사용 가능한 내용을 빠르게 파악하는 데 도움이 됩니다. Postman 컬렉션에 대해 자세히 알아보려면 “Using Postman” 페이지를 방문하세요. 

​

코드 샘플

선호하는 프로그래밍 언어로 이 엔드포인트를 설정하는 데 도움이 될 코드가 필요하신가요? 시작점으로 활용할 수 있는 다양한 코드 샘플을 저희 GitHub 페이지에서 확인하실 수 있습니다.

​

서드파티 라이브러리

커뮤니티에서 제공하는 서드파티 라이브러리를 활용해 빠르게 시작하세요. 적절한 버전 태그를 확인하면 v2 엔드포인트와 호환되는 라이브러리를 찾을 수 있습니다.

​

핵심 개념

​

인증

모든 X API v2 엔드포인트는 키와 토큰으로도 불리는 자격 증명 세트로 요청을 인증해야 합니다. 이러한 엔드포인트에 대한 요청 인증에는 OAuth 1.0a 사용자 컨텍스트, 앱 전용, 또는 OAuth 2.0 Authorization Code with PKCE 중 하나를 사용할 수 있습니다. 

OAuth 1.0a 사용자 컨텍스트는 성공적인 요청을 위해 API 키와 사용자 액세스 토큰 세트를 사용해야 함을 의미합니다. 액세스 토큰은 귀하가 대리하여 요청을 수행하는 해당 사용자와 연결되어 있어야 합니다. 다른 사용자의 액세스 토큰 세트를 생성하려면, 그 사용자가 3-legged OAuth 플로우를 통해 귀하의 앱을 승인해야 합니다.

OAuth 1.0a는 사용하기 어려울 수 있습니다. 이 인증 방법에 익숙하지 않다면 라이브러리를 사용하거나, Postman과 같은 도구를 사용하거나, OAuth 2.0을 사용해 요청을 인증할 것을 권장합니다.

OAuth 2.0 Authorization Code with PKCE는 애플리케이션의 스코프를 더 세밀하게 제어할 수 있게 해 주며, 여러 기기에 걸친 인가 플로우를 지원합니다. OAuth 2.0에서는 사용자 대리로 특정 권한을 부여하는 세분화된 스코프를 선택할 수 있습니다. 

앱에서 OAuth 2.0을 사용하려면, 개발자 포털의 앱 설정 섹션에 있는 앱 인증 설정에서 이를 활성화해야 합니다.

앱 전용은 요청에 앱 전용 액세스 토큰만 포함하면 됩니다. 개발자 앱에서 직접 앱 전용 토큰을 생성하거나, POST oauth2/token 엔드포인트를 사용해 생성할 수 있습니다.

​

개발자 포털, 프로젝트, 그리고 Developer 앱

X API v2 엔드포인트에서 작동하는 인증 자격 증명 세트를 발급받으려면, 먼저 개발자 계정을 등록하고 해당 계정 내에 프로젝트를 설정한 다음, 그 프로젝트 안에 Developer 앱을 생성해야 합니다. 이후 Developer 앱에서 키와 토큰을 확인할 수 있습니다.  

​

요청 한도

매일 수천 명의 개발자가 X API에 요청을 보냅니다. 이러한 요청의 방대한 양을 관리하기 위해 요청 한도가 각 엔드포인트에 적용되며, 이를 통해 앱 또는 인증된 사용자를 대신해 보낼 수 있는 요청 수가 제한됩니다. 

이 엔드포인트들은 앱 수준과 사용자 수준 모두에서 한도가 적용됩니다. 앱 한도는 개발자인 귀하가 특정 기간 동안 어떤 App에서든지(API Key와 API Secret Key 또는 앱 전용 Access Token을 사용하는 것으로 가정) 이 엔드포인트에 보낼 수 있는 요청 수가 제한됨을 의미합니다. 사용자 한도는 귀하가 요청을 대신 보내는 인증된 사용자가 어떤 Developer 앱 전반에서 List 조회를 수행할 수 있는 횟수가 제한됨을 의미합니다.

아래 차트는 각 엔드포인트의 요청 한도를 보여줍니다.

엔드포인트	HTTP 메서드	요청 한도
/2/lists/:id	GET	15분당 75회 요청
/2/users/:id/owned_lists	GET	15분당 15회 요청

필드 및 expansions

X API v2 GET 엔드포인트는 fields 및 expansions라는 도구 세트를 사용하여 API에서 반환받을 데이터를 정확히 선택할 수 있게 합니다. expansions 파라미터는 페이로드에서 참조된 객체를 확장해 포함할 수 있게 합니다. 예를 들어, ID로 List를 조회할 때 다음 expansions을 가져올 수 있습니다:

• owner_id

fields 파라미터는 서로 다른 데이터 객체 내에서 수신할 필드를 정확히 선택할 수 있게 합니다. 이 엔드포인트들은 주로 List 객체를 제공합니다. 기본적으로 List 객체는 id 및 name 필드를 반환합니다. list.created_at 또는 list.follower_count와 같은 추가 필드를 받으려면 list.fields 파라미터로 명시적으로 요청해야 합니다. 

X API v2 데이터 사전에 fields와 expansions를 함께 사용하는 방법에 대한 가이드를 추가했습니다.

아래 차트는 이 엔드포인트 그룹에서 사용할 수 있는 필드와 expansions를 보여줍니다:

엔드포인트	필드	Expansions
/2/lists/:id	list.fields user.fields	owner_id
/2/users/:id/owned_lists	list.fields user.fields	owner_id

​

페이지네이션

사용자 소유 목록을 조회하면 많은 데이터가 반환될 수 있습니다. 언제든지 일관되고 높은 성능의 결과를 제공하기 위해 페이지네이션을 사용합니다. 페이지네이션은 단일 응답으로 반환할 수 있는 양을 초과하는 결과가 있을 때 적용되는 X API v2 엔드포인트의 기능입니다. 이 경우 데이터는 여러 ‘페이지’로 나뉘어 반환됩니다. 결과를 페이지네이션으로 탐색하는 방법에 대해 자세히 알아보세요.