편집토론기록

도움말:미디어위키 API

미디어위키는 일반 편집자들을 위한 편집 폼 이외에도 텍스트 기반의 API(Application Programming Interface)를 공개하고, 이를 이용해 편집을 원할하게 할 수 있습니다. 이를 이용해서 CLI 환경에서도 미디어위키 기반의 위키를 편집하거나, 대량으로 문서를 조회하는데 이용할 수 있습니다.

리브레 위키에서는 이 URL을 통해 미디어위키 API에 접근이 가능합니다.

1 API를 사용하는 이유[편집]

위키 편집을 할 때 일반적으로는 편집 창을 이용하는 것이 편리합니다. 그러나 여러 문서에서 특정한 어구에 대해 찾아 바꾸는 작업처럼 단순 반복적 작업은 코딩을 이용해서 해결하기 쉬운 작업이 있습니다. 이럴 경우 인터프리터가 위키 편집 포맷을 직접 조작하는 것은 비효율적이기에 미디어위키에서는 API를 통해 CLI 환경에서도 편집을 할 수 있게 지원합니다.

1.1 API에 접근하는 방법[편집]

기본적으로 미디어위키는 api.php 문서에 도움말을 지원하고 있습니다. query처럼 GET 메소드로도 사용이 가능한 API는 주소창에 api페이지를 입력한 후 파라미터들을 단순 나열하는 식으로 처리가 가능합ㄴ.다. 그러나 일반적으로는 다음과 같은 방식을 권장합니다.

  • API 실험실을 이용해서 API 사용하기
  • POSTMAN 같은 다양한 메소드를 지원하는 웹 연결 클라이언트 사용하기
  • 파이썬의 requests 모듈 등 웹 연결 모듈을 이용해서 접근하기

미디어위키 공식 홈페이지 API 안내 페이지도 참조하실 수 있습니다.

2 사용 가능한 동작[편집]

사용자가 미디어위키 API에 접근해서 사용 가능한 동작은 다음과 같습니다. 일부 동작은 특수한 권한이 있어야 가능합니다. API에서 action에 할당되는 부분입니다.

2.1 일반적인 동작[편집]

주소창에 입력하는 것 만으로도 수행이 가능한 동작입니다. URL에 파라미터를 입력하는 것만으로도 수행 가능하지만 상당히 복잡해지므로 API실험실이나 프로그래밍 언어를 이용하는 것을 권장합니다.

  • checktoken(토큰의 유효성 검사)
  • help(지정한 모듈의 도움말 요청)
  • query(내용 검색) - 문서 조회, 사용자 편집 확인, 편집 등에 필요한 CSRF 토큰 조회 등 다양한 기능이 있습니다.

2.2 POST 메소드로만 동작 가능[편집]

URL을 직접 입력해서 동작이 불가능합니다. API를 조건을 확인하고 동작을 설정하기 위해서는 POSTMAN처럼 GET 이외의 메소드 입력을 지원하는 소프트웨어를 사용하거나 특수:ApiSandbox같은 도구를 이용하셔야 합니다.

  • createaccount(계정 생성)
  • edit(문서 편집) - CSRF 토큰이 필요합니다.
  • login(로그인, 인증 쿠키 가져옴) - CSRF 토큰값을 변경합니다.
  • logout(로그아웃) - CSRF토큰이 필요합니다.
  • options(환경 설정 변경) - CSRF 토큰이 필요합니다.
  • purge(문서 갱신)
  • resetpassword(비밀번호 재설정 이메일 보내기)
  • tag(태그 추가/제거) - CSRF 토큰이 필요합니다.
  • watch(주시 문서 추가/제거) -CSRF 토큰이 필요합니다.

2.3 특수 권한이 있어야 동작 가능[편집]

일부 동작들은 특수한 권한이 있어야 동작이 가능합니다.

  • block(차단) / unblock (차단 해제)
  • delete(문서 삭제) / undelete(삭제한 문서 복구) / revisiondelete(판 삭제/복구)
  • import(다른 위키의 문서 판 가져오기)
  • move(문서 이동)
  • patrol(문서 판 점검)
  • protect(문서 보호)
  • rollback(되돌리기)
  • upload(파일 업로드)
  • userrights(사용자 권한 변경)
  • validatepassword(비밀번호 확인)

3 API 실험실 이용하기[편집]

미디어위키 API 실험실 화면

특수:ApiSandbox(API실험실 혹은 API연습장)를 이용하면 미디어위키에서 사용가능한 API를 폼 형식으로 입력이 가능합니다. 우선 선택 가능한 동작(action)을 선택한 뒤, 왼쪽의 action 메뉴를 눌러서 세부 동작을 설정할 수 있습니다. 미디어위키 API에 익숙하지 않아도 API 조작을 쉽게 할 수 있는 도구입니다. 일반적으로 잘 사용되는 도구는 아니지만 다음과 같은 작업을 하실 수 있습니다.

3.1 미디어위키 쿼리 검색[편집]

이 부분은 도움말:미디어위키 쿼리 문서의 일부입니다.

미디어위키의 기능 중 특정한 조건의 문서들이나 사용자 기여 정보 등을 조회할 때 사용합니다. action=query라고 입력하면 동작을 수행할 수 있습니다. 주소창을 통해서 파라미터를 입력하는 일은 일반적으로 번거롭기에 API 실험실을 통해서 쉽게 접근하실 수 있습니다.

3.1.1 미디어위키 쿼리 예제[편집]

리브레 위키 문서에 존재하는 외부 링크 모두 찾기
조회 결과
API 실험실에서는 다음과 같은 순서대로 작업하시면 됩니다.
  1. 우선 main 부분에서 action은 query, format은 json으로 지정합니다.
  2. 왼쪽에 action=query 탭을 누른 뒤 prop창에 extlinks라고 입력합니다. (외부 링크) 그 다음에 titles에는 '리브레 위키'(따옴표는 지우고 입력)라고 입력합니다.
  3. 왼쪽에 format=json 탭을 누른 뒤 utf8항목을 켜줍니다. 이것이 있어야 한글이 깨지지 않고 출력합니다.
  4. 마지막으로 오른쪽 위의 요청하기 버튼을 누르면 결과가 나타납니다.
분류:나무위키 분류에 속하는 모든 문서 찾기
조회 결과
API실험실에서는 다음과 같은 순서대로 작업하시면 됩니다.
  1. 우선 main부분에서 action은 query, format은 json으로 지정합니다.
  2. 왼쪽에 action=query 탭을 누른 뒤 list 창에 categorymembers라고 입력합니다.(분류 안의 내용)
  3. 그 다음 list=categorymembers 탭을 누른 뒤 cmtitle 창에는 '분류:나무위키'(따옴표 제외하고 입력), cmnamespace 창에는 0(일반 문서만), cmlimit에는 max(최대 조회치)를 입력합니다.
  4. 왼쪽에 format=json 탭을 누른 뒤 utf8 항목을 켜줍니다. 이것이 있어야 한글이 깨지지 않고 출력합니다.
  5. 마지막으로 오른쪽 위의 요청하기 버튼을 누르면 결과가 나타납니다.

3.1.2 CSRF 토큰 찾기[편집]

미디어위키 API 작업들 상당수는 CSRF 토큰값을 요구합니다. 비록 API실험실을 이용해서 작업할 때에는 API 실험실 폼에서 알아서 찾아주는 링크를 제공하기에 이 작업을 할 필요는 없으나 프로그래밍을 할 때에는 선행작업이 필요하기에 URL을 암기하는 것이 좋습니다. 조회 결과

  1. 우선 API실험실에 들어간 뒤 action=query를 지정합니다.
  2. action=query 탭을 누른 뒤 meta 창에 tokens를 입력합니다. 그 다음 요청하기를 누르면 다음과 같은 형식으로 결과가 출력됩니다.
{
    "batchcomplete": "",
    "query": {
        "tokens": {
            "csrftoken": "(16진수 40자리)+\\"
        }
    }
}

3.2 문서 생성 및 편집[편집]

API실험실은 문서 편집을 할 때는 불편한 점이 많습니다. 우선 수정 전의 텍스트 내용도 확인할 수도 없고, 사용가능한 텍스트 편잡 옵션은 text(전체 편집), prependtext(앞부분 추가 텍스트), appendtext(뒷부분 추가 텍스트), section(문단번호, 새 문단일 경우는 new), sectiontitle(새 문단 제목) 정도이기에 기존 내용과 무관하게 문서 전체 혹은 문단 전체를 덮어쓰거나 앞/뒷부분에 추가하는 정도만 가능하기 때문입니다. 그러나 비슷한 포맷의 문서를 여러 개 생성할 때에는 API실험실이 상당히 유용하게 쓰일 수 있습니다. 다음과 같이 여러 문서를 추가할 때 유용하게 쓰실 수 있습니다.

문서 편집할 때에는 POST 메소드만 허용됩니다. 주소창에서는 입력할 수 없으며 POSTMAN 같은 웹 데이터 클라이언트를 이용해야 합니다.

API실험실을 이용해서 문서 생성하기
  1. 작성 전에 주의해야 할 점은 API실험실은 메모장처럼 위키 문법에 효과를 부여하지 않습니다. 따라서 위키 문법을 확실히 숙지할 때에만 사용하실 것을 권장드립니다.
  2. 우선 API실험실에 들어간 뒤 action=edit를 지정합니다.
  3. action=edit 탭을 누른 뒤 title 탭에 문서의 제목을 지정합니다.
  4. text 탭에 문서의 내용을 입력하고, summary 탭에는 편집 요약을 입력합니다.
  5. section에 번호를 입력하면 문단 순서에 따라 하위 문단의 내용을 편집할 수 있습니다. new라고 입력하면 새 문단 기호를 입력할 수 있습니다. 이 때에는 sectiontitle(문단 제목)도 지정해주세요.
  6. prependtext는 앞에 추가될 내용, appendtext는 뒤에 추가될 내용을 지정할 수 있습니다.
  7. 사소한 편집을 보증하기 위해서는 minor 옵션을 켜고, bot 편집을 보증하기 위해서는 bot 옵션을 켜면 됩니다.
  8. 새 문서임을 보증할 때에는 createonly 옵션을 켜는 것을, 새 문서를 생성하지 않기 위해서는 nocreate 옵션을 켜야 합니다. 넘겨주기를 보증하기 위해서는 redirect 옵션을 켜면 됩니다.
  9. 마지막으로 중요한 것이 바로 token 값을 채우는 겁니다. API 실험실에서는 토큰 자동 채우기 버튼이 있어서 이걸 눌러서 값을 채울 수 있습니다. 이후에 요청하기 버튼을 누르면 됩니다.
  10. API실험실을 이용하면 페이지 이동이 적고, 데이터 전송 속도도 조금 더 빠르기에 이 방식을 이용하면 비슷한 포맷의 문서를 대량 생산할 때에(특히 넘겨주기 문서) 편집창을 이용하는 방법보다 더 빠르게 작성할 수 있습니다.


리브레 위키 도움말
기초 사용법
위키 문법
특수 기능