Jump to content

API:에티켓

From mediawiki.org
This page is a translated version of the page API:Etiquette and the translation is 88% complete.
Outdated translations are marked like this.
Languages:

API를 사용할 때 따라야 할 규칙을 다루고 있는 문서입니다. See also the official guidelines about API usage on Wikimedia Foundation Governance wiki.

구체적 방안

요청 제한

요청에 대해 엄격한 제한을 적용하고 있지는 않으나, 당신의 요청으로 인해 사이트가 다운되지 않도록 유의해야 합니다. 대부분의 시스템 관리자들은 사이트의 안정성에 위협을 가할 수 있는 행동에 대해 별도의 부수적인 절차 없이 차단할 수 있는 권한을 가지고 있습니다.

요청을 동시에 여러 개를 보내지 않고, 먼저 보낸 요청이 처리될 때까지 기다린 다음 하나씩 보내는 방식으로 사이트가 요청을 처리하는 데 있어 안정성을 유지할 수 있습니다. 다음과 같은 방법으로 한 번의 요청에 여러 개의 파라미터를 싣어서 보내세요:

  • 요청을 각각 보내는 대신, 파이프 문자(|, 수직선)를 이용하여 titles=PageA|PageB|PageC와 같은 방식으로 요청을 보내세요.
  • 반복적인 요청에는 제너레이터 를 사용하세요.
  • 대역폭 사용량을 줄이기 위해 Accept-Encoding: gzip라고 적는 GZip 압축을 사용하세요.

편집을 하거나 상태를 수정하는 등 read-only 요청이 아닌 요청들은 보내는 데 제한이 있습니다. 정확한 제한 수치는 요청의 종류나 사용자 권한, 웹사이트 설정에 따라 다릅니다. 정확한 수치는 action=query&meta=userinfo&uiprop=ratelimits로 확인할 수 있습니다.

api.php?action=query&format=json&meta=userinfo&uiprop=ratelimits [try in ApiSandbox]

제한 수치를 넘으면 API error response 라는 응답을 받고, ratelimited라는 오류 코드를 출력합니다. 많은 사용자의 경우 요청을 다시 보내지만, 일반적으로 요청의 대기시간을 늘리는 것이 좋습니다. 자세한 내용에 대해선 Exponential backoff을 참고하세요.

편집된 판 파싱하기

revid 매개 변수를 사용하여 특정 편집 판을 검색하는 것은 서버에 부하를 줄 수 있습니다. 특정 편집 판을 검색하려면 oldid 매개변수를 사용하는 것이 좋습니다:

api.php?action=parse&format=json&prop=images&oldid=254862759 [try in ApiSandbox]

Maxlag 매개변수

당신의 프로젝트가 서버의 즉각적인 반응을 필요로 하는 게 아니라면, maxlag 매개변수를 사용하는 게 좋습니다. maxlag은 양의 정수로 표시된 초 단위의 시간으로 설정할 수 있습니다. 예시:

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

이것은 서버에 대한 부하가 높을 때 작업이 실행되는 것을 방지합니다. 높을수록 규칙을 엄격하게 지키는 것이고, 낮을수록 응답은 빨라집니다.

더 자세한 사항은 Manual:Maxlag parameter 에서 확인하세요.

유저 에이전트 정책에 따른 헤더 설정하기

유저 에이전트 헤더 설정으로 요청자가 누구인지 밝히는 것이 좋습니다. 이를 위해 User-Agent: clientname/version (contact information e.g. username, email) framework/version...를 사용하세요. PHP에서는 다음과 같은 방식으로 사용할 수 있습니다: 

ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');

일반적인 웹 사이트 주소를 단순 복사 붙여넣기하여 헤더로 사용하지 마세요. 사이트의 시스템 관리자는 헤더를 통해 문제가 발생했을 때 원인을 쉽게 파악할 수 있습니다.

브라우저 기반 자바스크립트로 API를 요청할 때 User-Agent의 형식으로 헤더를 설정하는 것은 대부분의 경우 제대로 작동되지 않습니다. 제대로 작동되기 위해선 Api-User-Agent과 같은 형식의 헤더를 사용하세요.

좀 더 자세한 내용은 m:사용자 에이전트 정책을 참고하세요.

데이터 형식 설정하기

모든 API 유저는 JSON 형식을 사용해야 합니다 . 자세한 내용은 API:데이터 형식 에서 확인하세요.

성능에 관한 문제

대량의 데이터를 API를 통해 요청하는 것은 어떤 경우에도 매우 비효율적입니다. 대부분의 위키미디어 위키에서는 데이터를 대량으로 얻는 더 빠른 방법을 지원하고 있습니다. 자세한 내용은 m:Research:Data과 wikitech:Portal:Data Services를 참조하십시오.

기타 참고 사항

당신의 요청이 캐시될 수 있는 데이터를 얻는 것이라면, 캐싱을 위한 방법을 마련해야 합니다. 그렇지 않으면 서버에 같은 데이터를 반복적으로 요청하게 됩니다. 일부 클라이언트는 데이터를 직접 캐시할 수 있지만 자바스크립트 클라이언트에서는 불가능합니다.

웹 서비스 API에서 데이터를 읽을 땐 가능한 GET 요청을 사용하도록 해야 합니다. POST 요청은 캐시가 불가능하기 때문입니다.

In exceptional cases where you really need to use POST for a read request, such as calling action=parse with a long string of wikitext, consider setting the Promise-Non-Write-API-Action: true header. This helps ensure that your POST request is processed by an application server in the closest data center, if appropriate. There is no need to set this header for GET requests, and neither should it be set when making cross-wiki requests within a wiki family using CentralAuth; see 작업 T91820.

같이 보기

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