API:데이터 형식

From mediawiki.org
This page is a translated version of the page API:Data formats and the translation is 95% complete.
Languages:

입력

API는 매개변수로 제공받은 HTTP 요청을 통해 application/x-www-form-urlencoded이나 multipart/form-data의 형태로 입력을 받습니다. (unlike REST API, the Action API currently does not support application/json input format.) 모든 모듈(하위 모듈 포함)들은 저마다 고유의 매개변수를 갖고 있으며, 매개변수들은 설명문서와 action=help에 수록되어 있습니다. action=paraminfo 를 통한 확인도 가능합니다.

인코딩

모든 입력은 정규화된 유니코드의 형식으로 유효한 UTF-8 형태여야 합니다. 미디어위키는 다른 형식의 경우 유니코드로 변환을 시도하나, 오류가 발생할 수 있습니다.

여러 값을 사용하는 매개변수

여러 값을 가지는 매개변수를 입력할 경우 param=value1|value2의 형식으로 파이프문자 |를 써서 요청할 수 있습니다. 요청 데이터에 파이프문자가 포함되어 있을 경우 U+001F(U+001F)를 param=%1Fvalue1%1Fvalue2라고 써서 매개변수 분리에 쓰이는 파이프문자와 요청 데이터에서 단순히 문자로 쓰이는 파이프문자를 구분합니다.

여러 값을 가지는 매개변수들은 모듈 설명문서에 수록되어 있습니다.

불리언 값을 사용하는 매개변수

HTTP를 이용한 요청에서 불리언 매개변수(또는 논리형 매개변수)를 명시할 경우 해당 값을 참으로 요청합니다. 생략할 경우 거짓으로 요청됩니다. 매개변수를 참으로 명기하는 가장 간편한 방법은 Parameter=라고 써서 비워두는 것입니다. 이럴 경우 인터넷 브라우저와 서버의 HTTP 요청을 받아들이는 프로그램은 값을 참으로 인식합니다.

타임스탬프

시간 정보를 불러오는 매개변수는 여러가지 형식으로 시간을 불러올 수 있습니다.

시간 정보는 따로 지정하지 않을 경우 첫 번째인 ISO 8601 형식으로 나옵니다.

출력

미디어위키에서 사용되는 표준적이며 기본적인 출력 형식은 JSON입니다. 이외의 형식은 권장되지 않습니다.

형식을 지정할 경우 format=yourformat을 사용해서 지정해야 합니다. yourformat에 들어갈 수 있는 값들은 다음과 같습니다.

  • json: JSON 포맷 (권장)
  • php: 직렬화된 PHP 포맷 (구식화됨)
  • xml: XML 포맷 (구식화됨)
  • txt: PHP print_r() 포맷 (1.27 에서 제거됨)
  • dbg: PHP var_export() 포맷 (1.27 에서 제거됨)
  • yaml: YAML 포맷 (1.27 에서 제거됨)
  • wddx: WDDX 포맷 (1.26 에서 제거됨)
  • dump: PHP var_dump() 포맷 (1.26 에서 제거됨)
  • none: 비어있는 응답을 출력합니다. 1.21+

예제

JSON의 형식으로 출력값을 받습니다.

api.php?action=query&titles=Main%20page&format=json [try in ApiSandbox]


응답

{
  "query": {
    "pages": {
      "217225": {
        "pageid": 217225,
        "ns": 0,
        "title": "Main page"
      }
    }
  }
}

따로 지정하지 않을 경우, 모든 모듈은 데이터를 JSON 형식으로 출력합니다. JSON 출력은 디버깅 과정에서 응답 데이터를 조금 더 쉽게 확인할 수 있는 방식을 지원합니다. 정리된 JSON을 얻기 위해 fm을 jsonfm의 형식으로 써넣는 것 대신, 가독성이 높은 HTML의 형식으로 데이터를 출력할 수 있습니다.

JSON 매개변수

다음 매개변수들은 format=json 또는 format=jsonfm과 함께 사용할 수 있습니다.

  • utf8: ASCII가 아닌 형식들로 표현된 문자열을 16진법으로 변환하는 방법 대신, UTF-8로 인코딩합니다. Type: boolean.
  • ascii: ASCII가 아닌 형식으로 표현된 문자열을 16진법으로 인코딩합니다. Type: boolean.
  • formatversion: 데이터 형식 버전을 명시적으로 정합니다. 1.25+
    • 1: 문서 내용의 글자들마다 *를 입력하여 ASCII가 아닌 형식으로 표현된 문자열을 16진법으로 변환하는 과거의 방식입니다.
    • 2: ASCII로 표현되지 않은 대부분의 문자열을 정리된 데이터 형식인 UTF-8로 변환하는 방식으로, 현재 사용되고 있는 방법입니다. (권장)
  • callback: Response in the JSON format, by wrapping the result in a JavaScript function call. For security reasons, these responses ignore any browser session cookies and respond without information specific to a current logged-in user. This means the following features are disabled for safety:
  • 토큰을 받을 때는 이 매개변수를 사용할 수 없습니다. 이 매개변수가 있을 때 위키의 내용을 변경하는 동작을 수행하는 것 또한 불가합니다.
  • action=login 를 이용해 로그인한 사용자는 무엇을 하더라도 로그인하지 않은 익명 사용자로 취급됩니다. 해당 위키가 익명 사용자의 API 이용을 허용하지 않을 경우, 추가적인 권한이 필요한 모듈은 작동하지 않습니다.

추가 참고사항

  • XML과 PHP 출력은 구식화되었으나 사용은 가능합니다. 태생적인 보안의 취약성 때문에 PHP을 사용할 경우 출력을 PHP로 하는 것은 피하는 것이 좋습니다. 다만 통상적으로 사용되는 방식이기 때문에 PHP 형식을 지원하는 것 뿐입니다.
  • 개발을 위한 도구인 라이브러리나 데이터 형식을 변환해주는 사이트에서 JSON 응답을 다른 형식으로 변환하는 여러 가지 방법을 다루거나 제공하고 있습니다. JSON을 CSV로 변환하거나 쉼표로 데이터들을 정리해주는 방법에 대해 확인할 수 있습니다.
  • 최근 바뀜 목록 같은 피드형 모듈의 경우 일반적인 형식 대신 다른 형식으로 출력될 수 있습니다. RSS나 Atom 대신 다른 형식을 원한다면 feedformat 매개변수를 이용하여 명기해주세요. 이렇게 하면 format에서 지정한 형식은 오류를 출력해야 할 때 오류의 내용을 표시하는 데 사용됩니다.

같이 보기


Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Data_formats/ko&oldid=6466289"