메인 콘텐츠로 건너뛰기

​
X API v2 엔드포인트 전반의 일관성

새로운 X API v2의 핵심 요소 중 하나는 엔드포인트 전반에서의 일관성입니다. 이는 반환 객체, 기능, 그리고 API 동작이 유사한 엔드포인트 간에 동일하게 유지됨을 의미합니다. 다음 요소들은 모든 엔드포인트에서 동일합니다:

​
경로 명명

경로 명명에는 항상 엔드포인트 버전이 포함되고, 그 뒤에 리소스가 옵니다. 그다음 경로에는 앞서 나온 리소스와 연결된 ID, 어떤 데이터를 반환할지 결정하는 데 도움이 되는 선택 동사(예: search, sample), 데이터가 어떤 방식으로 전달될지 결정하는 전달 동사(예: stream), 또는 기본 리소스와 관계가 있는 다른 리소스(예: /user/12/tweets)가 포함될 수 있습니다. 마지막으로, 엔드포인트가 쿼리 매개변수를 지원한다면 끝에 쿼리 매개변수를 추가할 수 있습니다. 다음은 이러한 경로 및 쿼리 항목을 구성하는 몇 가지 예시입니다: /version/resource/id?param1=value&param2=value /version/resource/delivery/selection?param1=value&param2=value 실제 요청 예: /2/tweets/1067094924124872705?expansions=attachments.media_keys&tweet.fields=author_id /2/users/2244994945?user.fields=created_at,description /2/tweets/search/stream /2/tweets/search/recent?query=snow

​
JSON 스키마

요청에 대한 응답은 JSON Schema를 사용해 정의됩니다. 이는 요청이 각 요소에 id가 있는 객체 집합을 배열 형태로 일관되게 반환함을 의미합니다. 요청은 id를 키로 사용하는 맵을 반환하지 않습니다.

​
응답 객체 및 매개변수

기본적으로 반환되는 객체는 해당 객체 유형의 각 엔드포인트에서 동일합니다:
  • id 객체는 항상 문자열입니다.
  • 매개변수와 응답 필드는 일관되게 미국식 영어 철자를 사용합니다.
  • 값이 없으면 필드는 비어 있거나 반환되지 않습니다.
  • entities 객체에는 게시물 텍스트에서 추출된 엔터티만 포함됩니다. 여기에는 urls, hashtags, mentions, cashtags가 포함됩니다.
  • media_keys 및 poll_ids 필드를 포함한 모든 카드 관련 정보는 attachments 객체로 반환됩니다.
다음은 단일 게시물 조회 엔드포인트의 예시 응답 객체입니다 (tweet.fields 매개변수를 author_id, entities로 설정한 경우): 
{
   "data": {
       "id": "1278747501642657792",
       "text": "Twitter의 Developer Labs가 출시된 지 1년이 되었습니다.\n\n차세대 #TwitterAPI를 구축하는 과정에서(곧 출시 예정), 그동안 배우고 개선한 내용을 확인하세요. https://t.co/WvjuEWCa6G",
       "author_id": "2244994945",
       "entities": {
           "urls": [
               {
                   "start": 188,
                   "end": 211,
                   "url": "https://t.co/WvjuEWCa6G",
                   "expanded_url": "https://blog.x.com/developer/en_us/topics/tools/2020/a-year-with-twitter-developer-labs.html",
                   "display_url": "blog.x.com/developer/en_u…",
                   "images": [
                       {
                           "url": "https://pbs.twimg.com/news_img/1278747527043362816/7HQRkQeV?format=jpg&name=orig",
                           "width": 1600,
                           "height": 600
                       },
                       {
                           "url": "https://pbs.twimg.com/news_img/1278747527043362816/7HQRkQeV?format=jpg&name=150x150",
                           "width": 150,
                           "height": 150
                       }
                   ],
                   "status": 200,
                   "title": "Twitter Developer Labs와 함께한 1년: 배우고 개선한 것들",
                   "description": "Labs는 무엇이 효과적이고 무엇이 그렇지 않은지, 여러분이 무엇을 선호하고 무엇을 선호하지 않았는지 파악하는 데 매우 유용했습니다.",
                   "unwound_url": "https://blog.x.com/developer/en_us/topics/tools/2020/a-year-with-twitter-developer-labs.html"
               }
           ],
           "hashtags": [
               {
                   "start": 106,
                   "end": 117,
                   "tag": "TwitterAPI"
               }
           ]
       }
   }
}

​
인증

모든 X API v2 엔드포인트는 인증이 필요합니다. 이 중 다수는 OAuth 2.0 Bearer Token 방식을 지원하며, 요청이 성공하려면 엔드포인트로의 요청에 베어러 토큰을 포함해야 합니다. 다른 사용자를 대신해 데이터를 생성, 수정 또는 조회하려면 권한 부여가 필요한 엔드포인트에서는 OAuth 1.0a 사용자 컨텍스트를 사용하세요. 즉, Developer 앱의 API 키와 토큰과 함께, 요청을 수행하려는 대상 사용자를 위해 발급한 사용자 액세스 토큰 세트를 제공해야 합니다. 3-legged OAuth 플로우를 통해 액세스 토큰을 획득할 수 있습니다. 이 권한 부여 헤더를 자동으로 생성해 주는 도구 또는 라이브러리를 사용하세요. 인증에 대한 자세한 내용은 인증 문서를 참고하세요.

​
필드

각 엔드포인트에서 반환되는 객체는 축약되어 있습니다. 개발자가 API 응답을 더 유연하게 구성할 수 있도록, 원하는 필드를 요청할 때 fields 매개변수를 사용합니다. 필드는 엔드포인트 전반에서 일관됩니다. 게시물 객체는 해당 객체가 반환되는 모든 엔드포인트에서 동일한 필드를 제공합니다. 유사한 엔드포인트 전반에 걸쳐 동일한 필드 집합을 조회할 수 있습니다. 예를 들어, 동일한 게시물 필드는 Posts 조회와 Users 조회에서 확장된 고정 게시물에 대해 동일하게 조회할 수 있습니다.

​
확장(expansions)

적절한 경우, expansions은 모든 중첩 id 필드(예: author_id와 같이 *_id로 명명된 모든 필드)에 사용할 수 있습니다. 또한 현재 객체의 최상위 식별자가 아닌 id를 가진 모든 필드에도 확장을 사용할 수 있습니다. 예를 들어 게시물 조회에서 게시물(Post)은 현재 객체이며, id 필드는 최상위 식별자입니다. author_id 또는 referenced_tweets.id 필드는 이러한 값을 쉼표로 구분하여 expansions 매개변수에 추가하면 전체 사용자 또는 게시물(Post) 객체로 확장할 수 있습니다. 이러한 필드와 관련해 발견하신 불일치 사항을 신고해 주세요.