5.6 KiB
| description |
|---|
| Misskey는 클라이언트, 연동 웹 서비스, 봇 등("어플리케이션"이라 합니다)을 개발할 수 있도록 API를 제공합니다. |
Misskey API
::: tip 이 문서는 아직 국문으로 번역되지 않아, 일부 영문으로 제공됩니다.
API 레퍼런스는 여기를 참고해주세요. :::
Misskey는 클라이언트, 연동 웹 서비스, 봇 등("어플리케이션"이라 합니다)을 개발할 수 있도록 API를 제공합니다. 스트리밍 API도 제공하고 있어, 실시간 호환성을 가진 어플리케이션을 제작할수도 있습니다.
::: tip 공식 Misskey SDK나 서드파티 라이브러리를 이용하면 이 문서의 몇몇 단계를 간소화하는 등 API를 더 간편하게 이용할 수 있습니다. 여기를 통해 자세히 알아보세요. :::
API를 사용하려면, 먼저 API를 사용하려는 계정과 연결된 엑세스 토큰을 얻어야 합니다. 이 문서에서는 엑세스 토큰을 얻는 과정과 API를 활용하는 기본적인 방법을 알아봅니다.
엑세스 토큰 얻기
API는 일반적으로 요청을 생성하기 위해 액세스 토큰이 필요합니다. 액세스 토큰은 사용자를 식별하고 API를 통한 작업을 제어하는 자격 증명 집합입니다.
::: tip 사용자와 엑세스 토큰 사이에는 한 개에서 여러 개의 연결이 존재하며, 한 사용자가 여러 엑세스 토큰을 생성하는 것도 가능합니다. :::
엑세스 토큰은 손쉽게 직접 얻거나 어플리케이션을 사용하려는 유저로부터 얻을 수 있습니다.
엑세스 토큰 수동으로 생성하기
엑세스 토큰은 Misskey Web의 '설정 > API'에서 생성할 수 있습니다.
::: warning 엑세스 토큰은 다른 사람과 공유하지 마십시오. :::
엑세스 토큰 생성 요청하기
어플리케이션의 사용자로부터 엑세스 토큰을 얻으려면, 뒤에 설명되어 있는 방법으로 요청할 수 있습니다.
::: tip 아래에서 설명하는 것은 MiAuth를 통해 앱을 만들지 않고도 액세스 토큰을 발행하는 방법입니다.
기존처럼 앱을 생성해 액세스 토큰을 취득할 수도 있습니다. :::
1단계
UUID를 생성하세요. 이 UUID는 앞으로 세션 ID라 부르게 됩니다.
::: warning 이 세션 ID는 매번 생성해야 하며, 재사용되어서는 안 됩니다. :::
2단계
어플리케이션의 인증 폼이 사용자의 브라우저에 표시될 것입니다. 인증 폼은 이러한 URL로 표시될 것입니다:
https://{host}/miauth/{session}
여기에서
{host}는 사용자의 인스턴스 호스트(주로 사용자로부터 직접 입력받습니다)이고,{session}은 세션 ID입니다.
이 URL의 쿼리 파라미터로 몇몇 옵션을 지정할 수도 있습니다:
| 이름 | 설명 |
|---|---|
name |
어플리케이션 이름 |
icon |
어플리케이션 아이콘 이미지 URL |
callback |
인증 후 사용자가 돌아갈 URL입니다. 쿼리 파라미터로 session이 추가됩니다. |
permission |
어플리케이션이 요청하는 권한입니다. 권한은 ,로 구분된 목록으로 요청됩니다. 권한 목록은 여기에서 확인할 수 있습니다. |
::: 예시
https://misskey.io/miauth/c1f6d42b-468b-4fd2-8274-e58abdedef6f?name=MyApp&callback=https%3A%2F%2Fmyapp.example.com%2Fcallback&permisson=write:notes,write:following,read:drive
:::
3단계
사용자가 어플리케이션 엑세스 권한을 부여하면, 다음 양식으로 POST 요청을 전송하면 토큰이 포함된 JSON이 응답으로 전송됩니다.
https://{host}/api/miauth/{session}/check
여기에서
{host}는 사용자의 인스턴스이며{session}은 세션 ID입니다.
응답에 포함된 항목은 다음과 같습니다:
| 이름 | 설명 |
|---|---|
token |
사용자에 대한 엑세스 토큰 |
user |
사용자 정보 |
Using the API
Once you have your API access token, you can use the API by making requests to the various endpoints.
::: tip
- All HTTP APIs are POST, and both request and response are in JSON format (excluding drive/files/create).
- Specify
Content-Type: application/jsonin the request header. - The access token is included in the request body JSON with the parameter name
i.
:::
Example of a body with an access token (for meta):
{
"i": "HogEFugA1341",
"detail": false
}
The access token is included in the request body JSON at the parameter i.
For more information on the API, see the API Reference.
::: warning Misskey does not use REST. :::
In addition to the HTTP API, Misskey also provides a streaming API. More information about the streaming API can be found here.
::: tip
Your Misskey instance also provides API documentation at /api-doc.
:::