메인 콘텐츠로 건너뛰기
이 페이지에서는 리스트 멤버 엔드포인트를 통합하는 데 필요한 도구와 핵심 개념을 다룹니다.

유용한 도구

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

Postman

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

코드 샘플

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

서드파티 라이브러리

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

핵심 개념

인증

모든 X API v2 엔드포인트는 키와 토큰이라고도 불리는 자격 증명을 사용해 요청을 인증해야 합니다. 리스트 조회(lookup) 엔드포인트에 대한 요청을 인증할 때는 OAuth 1.0a User Context, OAuth 2.0 Authorization Code with PKCE, 또는 App only 방식 중 하나를 사용할 수 있습니다. 그러나 관리(manage) 리스트 엔드포인트를 사용하려면 반드시 OAuth 1.0a User Context 또는 OAuth 2.0으로 인증해야 합니다. OAuth 1.0a User Context는 요청을 성공적으로 수행하려면 API Key와 사용자 Access Token 세트를 사용해야 함을 의미합니다. Access Token은 대신하여 요청을 수행하려는 사용자와 연관되어 있어야 합니다. 다른 사용자의 Access Token 세트를 생성하려면 해당 사용자가 3-legged OAuth flow를 사용해 여러분의 App을 승인해야 합니다. OAuth 1.0a는 사용하기 어려울 수 있습니다. 이 인증 방식에 익숙하지 않다면, 라이브러리를 사용하거나 Postman 같은 도구를 사용하거나, OAuth 2.0이나 App only 방식을 사용해 요청을 인증할 것을 권장합니다. OAuth 2.0 Authorization Code with PKCE는 애플리케이션의 스코프(scope)와 여러 디바이스에 걸친 권한 부여 플로우를 보다 세밀하게 제어할 수 있게 해 줍니다. OAuth 2.0을 사용하면, 사용자 대신 특정 권한을 부여하는 세분화된 스코프를 선택할 수 있습니다. App에서 OAuth 2.0을 사용하려면, 개발자 콘솔의 App 설정 섹션에 있는 App의 인증 설정에서 이를 활성화해야 합니다. App only 방식은 요청과 함께 App only Access Token만 전달하면 됩니다. App only Access Token은 개발자 App 내에서 직접 생성하거나, POST oauth2/token 엔드포인트를 사용해 생성할 수 있습니다.

개발자 콘솔, Project, 그리고 개발자 App

X API v2 엔드포인트와 함께 사용할 수 있는 인증 자격 증명 세트를 발급받으려면 개발자 계정에 가입한 후, 해당 계정 내에 Project를 설정하고 그 Project 안에 developer App을 생성해야 합니다. 그런 다음 개발자 App 내에서 자신의 키와 토큰을 확인할 수 있습니다.

요청 한도

매일 수만 명의 개발자가 X API에 요청을 보냅니다. 이처럼 방대한 양의 요청을 관리하기 위해, 각 엔드포인트에는 요청 한도가 설정되어 App 또는 인증된 사용자를 대신해 보낼 수 있는 요청 수를 제한합니다. 조회(GET) 엔드포인트에는 App 수준과 사용자 수준 두 가지 요청 한도가 적용되며, 관리(POST/DELETE) 엔드포인트에는 사용자 수준 한도만 적용됩니다. App 요청 한도는 개발자인 여러분이( API Key 및 API Secret Key 또는 App only Access Token을 사용하는 것으로 가정할 때) 특정 기간 동안 각 App에서 이 엔드포인트로 보낼 수 있는 요청 수가 제한된다는 의미입니다. 사용자 요청 한도는 여러분이 요청을 보내는 대상인 인증된 사용자가, 어떤 개발자 App을 사용하더라도 리스트 조회를 수행할 수 있는 횟수가 제한된다는 의미입니다. 아래 표는 각 엔드포인트의 요청 한도를 보여 줍니다.
EndpointHTTP methodRate limit
/2/lists/:id/membersGET15분당 900회 요청
/2/users/:id/list_membershipsGET15분당 75회 요청
/2/lists/:id/membersPOST15분당 300회 요청
/2/lists/:id/members/:user_idDELETE15분당 300회 요청

필드와 expansions

X API v2 GET 엔드포인트를 사용하면 fieldsexpansions라는 도구 세트를 통해 API에서 어떤 데이터를 반환받을지 정확히 선택할 수 있습니다. expansions 매개변수는 페이로드에서 참조된 객체를 확장하여 함께 포함할 수 있게 해줍니다. 예를 들어, 리스트 멤버를 조회할 때는 다음과 같은 expansions을 가져올 수 있습니다:
  • pinned_tweet_id
fields 매개변수는 서로 다른 데이터 객체 내에서 어떤 fields를 받을지 정확히 선택할 수 있게 해줍니다. 리스트 멤버 조회는 주로 user 객체를 반환합니다. 기본적으로 user 객체는 id, name, username 필드를 반환합니다. user.created_at 또는 user.description 같은 추가 필드를 받으려면 user.fields 매개변수를 사용하여 해당 필드들을 명시적으로 요청해야 합니다. fields and expansions를 사용하는 방법에 대한 가이드를 제공하고 있습니다. 아래 표는 각 조회 엔드포인트에서 사용할 수 있는 필드와 expansions를 보여줍니다:
EndpointFieldsExpansions
/2/lists/:id/membersuser.fields, tweet.fieldspinned_tweet_id
/2/users/:id/list_membershipslist.fields, user.fieldsowner_id
membership/members를 조회하면 많은 양의 데이터가 반환될 수 있습니다. 항상 일관되고 성능이 뛰어난 결과를 제공하기 위해 페이지네이션을 사용합니다. 페이지네이션은 단일 응답으로 반환할 수 있는 양보다 더 많은 결과를 반환하는 X API v2 엔드포인트에 포함된 기능입니다. 이런 경우 데이터는 여러 개의 ‘페이지’로 나뉘어 반환됩니다. 결과를 페이지 단위로 조회하는 방법에 대해 더 알아보세요.