Skip to main content

​
표준 v1.1과 X API v2 비교

표준 v1.1 GET users/show 및 GET users/lookup 엔드포인트를 사용해 오셨다면, 이 가이드의 목적은 표준과 X API v2의 사용자 조회(users lookup) 엔드포인트 간 유사점과 차이점을 이해하는 데 도움을 드리는 것입니다.
  • 유사점
    • OAuth 1.0a 사용자 컨텍스트
    • 요청당 사용자 수 제한
  • 차이점
    • 엔드포인트 URL
    • App 및 Project 요구 사항
    • 응답 데이터 형식
    • 요청 파라미터

​
유사점

OAuth 1.0a 사용자 컨텍스트 인증 방식 표준 엔드포인트는 OAuth 1.0a User Context를 지원하며, 새로운 X API v2 users 조회 엔드포인트는 OAuth 1.0a User Context와 App only를 모두 지원합니다. 따라서 이전에 표준 v1.1 users 조회 엔드포인트 중 하나를 사용하고 있었다면, X API v2 버전으로 마이그레이션하더라도 동일한 인증 방식을 그대로 사용할 수 있습니다. 사용 중인 인증 라이브러리/패키지에 따라 다를 수 있지만, App only 인증이 가장 시작하기 쉬운 방식인 경우가 많으며, 간단한 요청 헤더 설정만으로 구성할 수 있습니다. App only Access Token을 생성하는 방법은 이 App only 가이드를 참고하세요. 요청당 사용자 수 제한 표준 v1.1 GET users/lookup 엔드포인트에서는 요청당 최대 100명의 사용자를 지정할 수 있습니다. 이는 GET /users 및 GET /users/by 엔드포인트에도 동일하게 적용됩니다. 전체 100명의 사용자를 지정하려면, GET /users의 경우 ids 파라미터를, GET /users/by의 경우 username 파라미터를 쿼리 파라미터로 전달하고, 사용자 ID/username 목록을 쉼표로 구분된 목록으로 포함해야 합니다.

​
차이점

엔드포인트 URL App 및 Project 요구 사항 X API v2 엔드포인트를 사용하려면, 요청을 인증할 때 developer App의 자격 증명이 Project와 연결되어 있어야 합니다. 모든 X API v1.1 엔드포인트는 단독 App 또는 Project와 연결된 App의 자격 증명을 사용할 수 있습니다. 응답 데이터 형식 표준 v1.1과 X API v2 엔드포인트 버전 간 가장 큰 차이점 중 하나는 페이로드에 어떤 필드를 반환할지 선택하는 방식입니다. 표준 엔드포인트의 경우, 많은 응답 필드를 기본적으로 받게 되며, 이후 매개변수를 사용해 어떤 필드 또는 필드 집합을 페이로드에 반환할지 지정할 수 있습니다. X API v2 엔드포인트는 기본적으로 user id, name, username 필드만 제공합니다. 추가 필드나 객체를 요청하려면 fields 및 expansions 매개변수를 사용해야 합니다. 이 엔드포인트에서 요청한 모든 user 필드는 기본 user 객체에 포함되어 반환됩니다. 확장된 게시물 객체와 필드는 응답 내 includes 객체에 포함되어 반환됩니다. 그런 다음 user 객체와 확장된 게시물 객체 양쪽에 있는 ID를 매칭하여, 확장된 객체를 다시 user 객체와 연결할 수 있습니다. 이 새로운 매개변수에 대해서는 각 가이드를 참고하시거나, fields 및 expansions 사용 방법에 대한 가이드를 읽어 보시기를 권장합니다. 또한 표준 v1.1 필드를 새로운 v2 필드에 매핑하는 데 도움이 되는 데이터 형식 마이그레이션 가이드를 제공합니다. 이 가이드에서는 v2 요청에서 특정 필드를 반환하기 위해 전달해야 하는 expansions 및 field 매개변수를 구체적으로 안내합니다. 특정 필드를 요청하는 방식의 변경 외에도, X API v2는 Post 및 user 객체를 포함하여 API가 반환하는 객체에 대해 새로운 JSON 설계를 도입합니다.
  • JSON 루트 레벨에서, 표준 엔드포인트는 게시물 객체를 statuses 배열로 반환하는 반면, X API v2는 data 배열로 반환합니다.
  • 리트윗 및 인용된 “statuses”를 참조하는 대신, X API v2 JSON은 리트윗 및 인용된 Tweet을 참조합니다. contributors, user.translator_type과 같은 많은 레거시 및 사용 중단 필드는 제거됩니다.
  • 게시물 객체에서 favorites, user 객체에서 favourites를 모두 사용하는 대신, X API v2는 like라는 용어를 사용합니다.
  • X는 값이 없는 JSON 값(예: null)은 페이로드에 기록하지 않는 규칙을 채택하고 있습니다. 게시물 및 user 속성은 null이 아닌 값을 가진 경우에만 포함됩니다.
또한 Post 객체에 다음과 같은 새로운 필드 집합을 도입했습니다.
  • conversation_id 필드
  • context 및 entities를 포함하는 두 개의 새로운 annotations 필드
  • 여러 개의 새로운 metrics 필드
  • 특정 게시물에 누가 답글을 달 수 있는지를 보여주는 새로운 reply_setting 필드
요청 매개변수 다음 표준 v1.1 요청 매개변수는 X API v2에서 다음과 같은 매개변수에 해당합니다.
표준X API v2
user_idids
screen_nameusername
또한 X API v2에서 지원되지 않는 표준 users 조회 요청 매개변수 집합도 있습니다.
표준설명
include_entities이 매개변수는 게시물 페이로드에서 entities 노드를 제거하는 데 사용됩니다. 이 기능은 추가적인 fields 및 expansions 기능으로 대체되었습니다.

​
코드 예제

다음 예제는 표준 v1.1 엔드포인트와 이에 대응하는 v2 엔드포인트를 보여줍니다. 단일 사용자 조회: v1.1 GET users/show → v2 GET /users/by/username/:username
cURL (v1.1)
curl --request GET \
  --url 'https://api.x.com/1.1/users/show.json?screen_name=XDevelopers' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'
여러 사용자 조회: v1.1 GET users/lookup → v2 GET /users/by
cURL (v1.1)
curl --request GET \
  --url 'https://api.x.com/1.1/users/lookup.json?screen_name=XDevelopers,X,XAPI' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'