Skip to content

Commit

Permalink
feat: localize root docs and add missing files
Browse files Browse the repository at this point in the history
  • Loading branch information
jdh5968 committed Jan 7, 2023
1 parent 9c38514 commit e11ea6a
Show file tree
Hide file tree
Showing 8 changed files with 77 additions and 81 deletions.
6 changes: 5 additions & 1 deletion src/ko/docs/admin/cdn.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,21 @@
# Set up a CDN

When publishing your Misskey instance, we strongly recommend using a CDN such as [Cloudflare](https://www.cloudflare.com/).

Using a CDN has the following advantages

- You can have static content cached, which reduces the load on your server
- The IP address of the server is less exposed, which can mitigate DoS attacks etc.

## Caching

Misskey Web is completely static and does not require a server to run. Therefore the whole Misskey Web can be cached in a CDN.
The Misskey API cannot be cached.

You need to configure the following settings in your CDN

- Cache all requests except `/api/*`.

::: tip
:::
You don't need to clear the cache when you update Misskey.
::::
40 changes: 0 additions & 40 deletions src/ko/docs/api/common.json5

This file was deleted.

38 changes: 25 additions & 13 deletions src/ko/docs/api/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,11 @@ description: 'Misskey exposes an API that you can use to develop Misskey clients
---

# Misskey API

Misskey exposes an API that you can use to develop Misskey clients, Misskey-connected web services, bots, etc. ("Applications").
We also have a streaming API, so you can create applications with real-time capabilities.

::: tip
:::
By using the official Misskey SDK or third party libraries, you can use the API more conveniently, for example by simplifying some of the steps described in this document.
See [here](TODO) for more information about libraries.
:::
Expand All @@ -15,77 +16,88 @@ To start using the API, you will need to obtain an **access token** associated w
This document will walk you through the process of obtaining an access token and then show you how to use the API in a basic way.

## Getting an access token

The API generally requires an access token to make a request.
An access token is a set of credentials associated with a user, which identifies the user using the API and controls what operations each access token is authorised to perform.

::: tip
:::
There is a one-to-many relationship between a user and the access token associated with that user, and multiple access tokens can be issued for a given user.
:::

You can easily [obtain an access token for yourself](#Manually-issue-an-access-token), or you can [obtain an access token for an user who will be using your application](#Request-an-access-token-to-be-issued).

### Manually issue an access token

You can issue your own access token in Misskey Web under 'Settings > API'.

::: danger
Please do not share your access token with anyone.
:::

### Request an access token to be issued

To obtain an access token for a user of the application ( simply "the user"), you can request it to be issued in the following way.

#### Step 1

Generate a UUID. This will be referred to as the **session ID** from now on.

::: danger
This session ID should be generated each time and should not be reused.
:::

#### Step 2

The application authentication form should be displayed in the user's browser. The authentication form can be opened with a URL similar to this:

```:no-line-numbers
https://{host}/miauth/{session}
```

where

- `{host}` is the host of the user's instance (usually this is entered by the user) and
- `{session}` is the session ID.

You can also set a few options as query parameters to the URL:

| name | description |
| ---- | ---- |
| `name` | application name |
| `icon` | application icon image URL。 |
| `callback` | The URL to which the user will be redirected after authentication, with the session ID added to the redirect with the query parameter `session`. |
| name | description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | application name |
| `icon` | application icon image URL。 |
| `callback` | The URL to which the user will be redirected after authentication, with the session ID added to the redirect with the query parameter `session`. |
| `permission` | The permissions that the application requires. <br>List the permissions to be requested, separated by `,`. The list of permissions can be found [here](TODO). |

::: tip Example
::: 팁 Example

```:no-line-numbers
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
```

:::

#### Step 3

After the user has been granted application access, a POST request to a URL of the following form will return JSON containing the access token as a response.

```:no-line-numbers
https://{host}/api/miauth/{session}/check
```

where

- `{host}` is the host of the user's instance and
- `{session}` is the session ID.

The properties included in the response are as follows:

| name | description |
| ---- | ---- |
| `token` | access token for the user |
| `user` | information about the user |
| name | description |
| ------- | -------------------------- |
| `token` | access token for the user |
| `user` | information about the user |

## Using the API

Once you have your API access token, you can use the API by making requests to the various endpoints.
**All HTTP APIs are POST and both request/response are in JSON format.**

Expand All @@ -99,6 +111,6 @@ For more information on the API, see the [API Reference](TODO).

In addition to the HTTP API, Misskey also provides a streaming API. More information about the streaming API can be found [here](./streaming/).

::: tip
:::
Your Misskey instance also provides API documentation at `/api-doc`.
:::
30 changes: 25 additions & 5 deletions src/ko/docs/api/streaming/index.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
description: 'The streaming API provides real-time information (e.g., new posts in the timeline, reactions, followers, etc.) and various other operations.'
description: "The streaming API provides real-time information (e.g., new posts in the timeline, reactions, followers, etc.) and various other operations."
---

# Streaming API

::: tip
:::
You should read the [Misskey API documentation](../index.md) first.
:::

Expand All @@ -21,10 +21,11 @@ wss://{host}/streaming?i={token}
```

where

- `{host}` is the host of the instance you want to connect to.
- `{token}` is the users access token.

::: tip
:::
You can also connect without the access token, but this will limit the information you receive and operations you can perform.
:::

Expand All @@ -35,16 +36,18 @@ To receive such events, you need to join a **channel** on the stream, as describ
**All data should be encoded as JSON.**

## Channel

Misskey's streaming API has the concept of channels. This is a mechanism for separating the information to be sent and received.
By joining channels on the stream, you will be able to receive various kinds of information and send information.

::: tip
:::
You can join multiple channels simultaneously on a single stream connection.
:::

The following sections describe how to use the channels. To see what channels are available, please refer to the [Channel List](./channel/index.md).

### Joining a channel

To join a channel, send the following JSON data on the stream:

```js
Expand All @@ -61,18 +64,21 @@ To join a channel, send the following JSON data on the stream:
```

where

- `channel` is the name of the channel you want to connect to. The types of channels are described later in this section.
- `id` is an arbitrary ID for interacting with that channel. This is necessary to identify which channel the message is coming from, because a stream contains multiple channels. This ID can be something like a UUID or a random number.
- `params` are parameters required when joining a channel. Different channels require different parameters when connecting. When connecting to a channel that does not require parameters, this property can be omitted.

::: tip
:::
The ID is not per channel but per channel connection, because a channel may be needed multiple times but with different parameters.
:::

### Receiving messages from channels

For example, a timeline channel will send out a message when there is a new post. By receiving the message, you will know in real time that a new post has been published on your timeline.

When a channel issues a message, the following JSON data is sent:

```js
{
type: 'channel',
Expand All @@ -87,14 +93,17 @@ When a channel issues a message, the following JSON data is sent:
```

where

- `id` is the ID that you set when connecting to that channel as mentioned above. This lets you know from which channel (instantiation) this message is coming.
- `type` is the type of message. The types of messages that get sent depend on the channel.
- `body` holds the content of the message. The content of the message depends on the channel.

### Sending a message to a channel

On some channels, it is also possible to send messages and perform other operations in addition to receiving messages.

To send a message to a channel, send the following JSON data to the stream:

```js
{
type: 'channel',
Expand All @@ -109,12 +118,15 @@ To send a message to a channel, send the following JSON data to the stream:
```

where

- `id` is the ID that you set when connecting to that channel as mentioned above. This lets you determine which channel (instantiation) the message is for.
- `type` is the type of message. Different channels accept different types of messages.
- `body` contains the content of the message. Different channels accept different message contents.

### Disconnecting from a channel

To disconnect from a channel (instantiation), send the following JSON data to the stream:

```js
{
type: 'disconnect',
Expand All @@ -125,9 +137,11 @@ To disconnect from a channel (instantiation), send the following JSON data to th
```

where

- `id` is the ID that you set when connecting to that channel as mentioned above. This lets you determine which channel (instantiation) you want to disconnect from.

## Capturing Notes

Misskey provides a mechanism called note capture. This is the ability to receive a stream of events for a given note.

For example, let's say you grab a timeline and display it to your users. Let's say someone reacts to one of the posts in the timeline.
Expand All @@ -140,6 +154,7 @@ The following sections describe how to use the note capture function. To see wha
### Capturing a Note

To capture a note, send the following JSON data to the stream:

```js
{
type: 'subNote',
Expand All @@ -150,11 +165,13 @@ To capture a note, send the following JSON data to the stream:
```

where

- `id` is the ID of the note you want to capture.

When you send this message, you are asking Misskey to capture the note, and events related to that note will then be streamed to you.

For example, when a note gets a reaction, you will see a message like the following:

```js
{
type: 'noteUpdated',
Expand All @@ -170,6 +187,7 @@ For example, when a note gets a reaction, you will see a message like the follow
```

where

- `body.id` will be set to the ID of the post that triggered the event.
- `body.type` will be the type of the event.
- `body.body` will contain the details of the event.
Expand All @@ -179,6 +197,7 @@ where
If you no longer want to receive events related to a note, such as when it no longer appears on your screen, you can remove the capture request.

Send the following JSON data:

```js
{
type: 'unsubNote',
Expand All @@ -189,6 +208,7 @@ Send the following JSON data:
```

where

- `id` is the ID of the note you want to uncapture.

Once you send this message, no more events related to that note will be sent to you.
2 changes: 1 addition & 1 deletion src/ko/docs/features/drive.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Drive
Drive is a feature that allows you to manage your files on Misskey.

::: tip
:::
Technically speaking, the drive can be seen as an interface where all the files are centrally managed on Misskey's system, which is also open to users.
:::

Expand Down
5 changes: 3 additions & 2 deletions src/ko/docs/features/mute-and-block.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ If you don't like a user, you can mute them to make them disappear from your tim
Alternatively, you can block a user to prevent them from seeing your content or engaging with you in any way.
People won't know that you have muted them, but they will know that you have blocked them. It is up to you to decide which option you prefer.

::: tip
:::
Mute and block can be used together.
:::

Expand All @@ -23,11 +23,12 @@ If you mute a user, the following content about that user will no longer appear

To mute a user in Misskey Web, open the menu on the user page of the user in question and press the "Mute" button.

::: tip
:::
They will not be notified that you have muted them, and they will not know that you have muted them.
:::

## Blocking

If you block a user, they will not be able to see your content and they will not be able to do any the following actions:

- follow you
Expand Down
2 changes: 1 addition & 1 deletion src/ko/docs/features/reaction.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Usually, ActivityPub's "Like" is implemented as a favorite.
## Reactions from remote instances
Since Misskey does not have likes, a "Like" from a remote instance will be displayed as a '👍' reaction.

::: tip
:::
Your instance administrator may change this to be displayed as a '⭐' reaction.
If you are an admin, see [here](../admin/default-reaction.md).
:::
Expand Down
Loading

0 comments on commit e11ea6a

Please sign in to comment.