API:Main page/ko


 * 입문자들을 위한 개요입니다. 더 자세한 하위 주제들은 오른쪽 메뉴 에서 보세요.

미디어위키 웹 API는 HTTP 위에서 기능,데이터,메타 데이터로 편리하게 접근할 수 있게 하는 웹 서비스입니다.

소개
"내부 API" 또는 "PHP API"에 관심이 있으시다면, PHP 개발자가 미디어위키에 새로운 기능을 추가할 수 있게 하는 확장 인터페이스를 보세요.

미디어 위키 웹 API는 유지보수를 위해 미디어위키 설치본 모니터링이나 붓을 만드는데 사용됩니다. 미디어위키 데이터베이스에 들어 있는 데이터로의 고수준의, 직접적인 접근을 제공합니다. 클라이언트 프로그램들은 웹 서비스로의 HTTP 요청을 만들어 자동으로 위키에 로그인하고, 데이터를 얻고, 변경 사항을 게시할 수 있습니다. 지원되는 클라이언트들 중에는 붓, Navigation popups과 LiveRC와 같은 가벼운 웹-기반 자바스크립트 클라이언트, Vandal Fighter와 같은 엔드유저 어플리케이션, 그리고 다른 웹 사이트([//tools.wmflabs.org 툴 연구소]' 유틸)등이 있습니다.

새로운 미디어위키 설치본에서 웹서비스는 기본적으로 활성화되어 있으나 관리자가 비활성화 시킬 수 있습니다.

미디어위키는 두 개의 외부에 노출된 인터페이스들을 가집니다.


 * Special:Export 페이지는 대규모의 위키 내용를 XML 형태로 내보낼 수 있습니다. 더 자세한 정보는 meta.wikimedia.org의 내보내기 도움말 글을 읽어보세요.
 * 표준 웹 기반 인터페이스 (이 페이지를 보기 위해 지금 사용하고 있는 것일 수도 있음) 웹기반 인터페이스 사용에 관한 정보는 을 읽어보세요.

예시
이 URL은 영어 위키페디아에 Main Page의 내용를 전송하도록 요청합니다.

이 URL에 HTTP GET 요청을 만드도록 아무 프로그래밍 언어를 사용하거나 브라우저로 이 링크를 접속하면, "Main Page"라 명명된 페이지의 현재 위키 마크업을 포함하는 JSON 문서를 받게 됩니다. format을 jsonfm으로 바꾸면 디버깅에 좋게 잘 만들어진 HTML 결과가 반환됩니다.

이것이 어떻게 작동하는 지 저 URL을 조각내봅시다.

접속점
이것이 "접속점"입니다. 미디어위키 웹 서비스 API의 홈 페이지와 비슷합니다. 이 이 웹사이트의 기초 URL 인 것처럼, 이 URL은 영어 위키피디아의 API의 기초 URL입니다.

만약 영어 위키피디아를 사용하는 프로그램을 만들고 있다면,구성되는 모든 URL은 이 기초 URL로 시작할 것이다. 만약 다른 미디어위키를 사용하고 계시다면, 그것의 다른 접속점을 찾아 대신 써야할 것입니다. 모든 위키미디어 위키들은 이 규칙을 따르는 접속점들을 가집니다.

이후로, 접속점으로의 RSD를 가집니다: 아무 페이지의 HTML 소스 안에서  을 찾고   URL를 추출하세요; 실제 링크는 추가적인 정보를 포함합니다. 예를 들어, 이 위키에서는 이렇습니다:

그 외에는, 접속점의 정확한 위치를 찾을 확실한 방법이 없습니다. 만약 운이 좋거나 index.php로의 절대 경로가 이상한 rewrite 규칙에 의해 숨겨지지 않았다면 "편집" (또는 기록) 링크를 취하고 index.php를 api.php로 바꾸거나, 만약 아니면 기본 스크립트 경로를 사용할 수 있을 것입니다. ( 처럼)

이제 URL의 쿼리 문자열 안 매개변수로 넘어갑시다.

형식
이는 Wikimedia 웹 서비스 API에게 우리는 데이터가 JSON 형식으로 반환됬으면 좋겠다고 요청합니다. 또한 을 시도하여 디버깅에 좋은 HTML 버전으로 결과를 받을 수 있습니다. 예상 밖으로 API가 XML와 같은 여러개의 출력 형식과 네이티브 PHP을 지원하여도, JSON을 제외하고 모든 형식들을 제거할 계획이 있기에, JSON 이외의 형식은 사용하지 않는 게 좋습니다.

기능
이것은 기능입니다. 미디어위키 웹 서비스 API는 50개 이상의 기능들을 지원하며, [//en.wikipedia.org/w/api.php API 레퍼런스]에 모두 문서화되어 있습니다. 이 경우에 있어서, 우리가 어떤 데이터를 얻고 싶다고 API에게 알리기 위해 "query"를 써보겠습니다.

"query" 기능은 API의 가장 중요한 기능들 중 하나이며, extensive documentation of its own를 가집니다. 뒤에 오는 것은 그저 한 예제의 설명입니다.

기능-지정 매개변수
예제 URL의 나머지는 "query" 기능에서 사용하는 매개변수들을 포함합니다. 여기서, 우리는 웹 서비스 API에게 우리는 "Main Page"라 불리는 위키 페이지에 대한 정보를 원한다고 알립니다. (%20은 퍼센트 인코딩된 스페이스입니다.) 만약에 여러개의 페이지들과 함께 작업하려면, 네트워크 및 서버 리소스 최적화를 위해 모두를 하나의 요청에 넣는 것을 고려해보세요: 더 자세한 사항은 query 문서를 참고하세요.

이 매개변수는 웹 서비스 API에게 페이지의 특정 판에 관심이 있다고 알립니다. 아무 판 정보도 지정하지 않는다면 API는 최신 판에 대한 정보를 제공할 것입니다, 이 URL은 최신 버전의 위키백과 메인 페이지를 가라킵니다.

최종적으로, 이 매개변수는 웹 서비스 API에게 페이지의 최신 판을 원한다고 알립니다. 만약 대신 을 쓴다면, 최신 판의 내용과 가장 최근의 판을 만든 사용자와 이름을 받을 것입니다.

이것은 그저 하나의 예제입니다. 쿼리들은 여기서 더 자세히 설명되어 있으며,API 레퍼런스는 가능한 기능들 모두와 에 들어 갈 수 있는 값들과, 기타 등등을 열거합니다.



시작하기
미디어위키 웹 서비스 API를 사용하기 전에, 이 문서들을 반드시 읽어주십시오.
 * The FAQ.
 * The page about input and output formats
 * The page about errors and warnings
 * Any policies that apply to the wiki you want to access, such as (for Wikimedia Foundation wikis) our terms of use. These terms apply to you when you access or edit using the web service API, just as they do when you use your web browser.

Beyond that point, what you need to read depends on what you want to do. The right-hand menu links to detailed, task-specific documentation, and some more general guidelines are given below.

Identifying your client
When you make HTTP requests to the MediaWiki web service API, be sure to specify a  header that properly identifies your client. Don't use the default  provided by your client library, but make up a custom header that identifies your script or service and provides some type of means of contacting you (e.g., an e-mail address).

An example User-Agent string might look like: MyCoolTool/1.1 (http://example.com/MyCoolTool/; MyCoolTool@example.com) BasedOnSuperLib/1.4

On Wikimedia wikis, if you don't supply a  header, or you supply an empty or generic one, your request will fail with an HTTP 403 error (cf. User-Agent policy). Other MediaWiki installations may have similar policies.

If you are calling the API from browser-based JavaScript, you won't be able to influence the  header: the browser will use its own. To work around this, use the  header:

In PHP, you can identify your user-agent with code such as this:

Or if you use cURL:

Logging in
Your client will probably need to log in to MediaWiki, possibly via its own user account. See the login manual page for details.

API etiquette
Please also read: API:Etiquette

If your requests obtain data that can be cached for a while, you should take steps to cache it, so you don't request the same data over and over again. More information about rate-limiting, concurrency, and general API etiquette can be found at API:Etiquette. Some clients may be able to cache data themselves, but for others (particularly JavaScript clients), this is not possible.

Per the HTTP specification, POST requests cannot be cached. Therefore, whenever you're reading data from the web service API, you should use GET requests, not POST.

Also note that a request cannot be served from cache unless the URL is exactly the same. If you make a request for, and cache the result, then a request for   will not go through the cache — even though MediaWiki returns the same data!

You should take care to normalize the URLs you send to the MediaWiki web service, so that slightly different user input won't cause you to waste time on unnecessary HTTP requests. You can normalize a list of page titles by removing duplicates and sorting the titles alphabetically. Similar techniques will work for other kinds of data.

Useful links
The menu bar on the right side of this page links to more detailed, task-specific documentation. Here are some links having to do with the API as a whole:


 * The API sandbox available on all Wikimedia wikis makes it easy to try out different actions interactively.
 * [//en.wikipedia.org/w/api.php The API reference] contains automatically-generated descriptions of all actions and parameters.
 * Hook into Wikipedia information using PHP and the MediaWiki API (IBM developerWorks article, 17 May 2011)
 * Hook into Wikipedia using Java and the MediaWiki API (6 April 2012)
 * The API tutorial leads you through hands-on exercises and includes a training video.
 * Mailing list for notifications and questions: API mailing list
 * Low-traffic mailing list for announcements only (all posts to this list are posted to mediawiki-api as well): mediawiki-api-announce
 * View and report API bugs: Phabricator (When reporting new bugs, don't forget to set Projects=MediaWiki-API)
 * The current MediaWiki database schema
 * The current MediaWiki database schema

Archived links

 * 2006 API discussion