sharkey/src/docs/ko-KR/api.md

# Misskey API

Misskey API를 사용하여 Misskey 클라이언트, Misskey 연계 웹 서비스, 봇 등(이하 "애플리케이션"이라고 부릅니다)을 개발할 수 있습니다. 스트리밍 API도 있기 때문에 실시간 애플리케이션을 만들 수도 있습니다.

API를 사용하려면 먼저 액세스 토큰을 취득해야 합니다. 이 문서에서는 액세스 토큰을 취득하는 절차를 설명한 후 기본적인 API 사용법을 설명합니다.

## 액세스 토큰 가져오기
기본적으로 API는 요청 시에 액세스 토큰이 필요합니다. API에 요청하는 것이 자기 자신인지, 불특정한 유저에게 사용하는 애플리케이션인지에 따라 취득 절차가 달라집니다.

* 전자의 경우: [「자기 자신의 액세스 토큰을 수동으로 발급하기」](#自分自身のアクセストークンを手動発行する)로 진행
* 후자의 경우: [「애플리케이션 사용자에게 액세스 토큰 발급을 요청하기」](#アプリケーション利用者にアクセストークンの発行をリクエストする)로 진행

### 자기 자신의 액세스 토큰을 수동으로 발급하기
「설정 > API」에서 자신의 액세스 토큰을 발급할 수 있습니다.

[「API 사용 방법」으로 이동](#APIの使い方)

### 애플리케이션 사용자에게 액세스 토큰 발급을 요청하기
애플리케이션 사용자의 액세스 토큰을 취득하려면, 다음 순서로 발급을 요청합니다.

#### 1 단계

UUID를 생성합니다. 이것을 세션 ID라고 부릅니다.

> 이 세션 ID는 매번 새로 생성하는 것이 아닙니다.

#### 2 단계

`{_URL_}/miauth/{session}`을 사용자의 브라우저에 입력합니다. `{session}` 부분은 세션 ID로 대체해서 입력합니다.
> 예: `{_URL_}/miauth/c1f6d42b-468b-4fd2-8274-e58abdedef6f`

표시할 때 URL에 쿼리 매개변수로 몇 가지 옵션을 설정할 수 있습니다:
* `name` ... 애플리케이션 이름
    * > 예: `MissDeck`
* `icon` ... 애플리케이션 아이콘의 이미지 URL
    * > 예: `https://missdeck.example.com/icon.png`
* `callback` ... 인증이 끝난 후 리디렉션되는 URL
    * > 예: `https://missdeck.example.com/callback`
    * 리디렉션 할 시, `session`이라는 쿼리 매개변수로 세션 ID가 붙습니다.
* `permission` ... 애플리케이션이 요구하는 권한
    * > 예: `write:notes,write:following,read:drive`
    * 요구하는 권한을 `,`으로 구분해서 작성합니다.
    * 권한의 종류에 대해서는 [API 레퍼런스](/api-doc)에서 확인할 수 있습니다.

#### 3 단계
사용자가 발급을 허용한 후, `{_URL_}/api/miauth/{session}/check`에 POST 요청을 하면 응답으로 액세스 토큰을 포함한 JSON이 반환됩니다.

응답에 포함되는 속성:
* `token` ... 유저의 액세스 토큰
* `user` ... 유저 정보

[「API 사용 방법」으로 이동](#APIの使い方)

## API 사용 방법
**API는 모두 POST 방식이며, 요청/응답 모두 JSON 형식입니다. REST가 아닙니다.** 액세스 토큰은 `i`라는 매개변수로 요청에 포함됩니다.

* [API 레퍼런스](/api-doc)
* [스트리밍 API](./stream)