apiary.apib

FORMAT: 1A
HOST: https://api.frost-sns.ml/

# Frost-API (日本語)
- **情報が古くなっています。新しいAPIリファレンスは[こちら](https://github.com/Frost-Dev/Frost-API/wiki/api-docs-(ja))です。**
- Frost-APIは公式アプリケーションを含むすべてのFrostクライアントがFrostのコンテンツを利用するためのAPIです。
- 全てのリクエストは`X-Api-Version`ヘッダーによってAPIのバージョンが指定されている必要があります。
- 権限を必要とするエンドポイントへのリクエストではヘッダーに `X-Application-Key` と `X-Access-Key` が付加されている必要があり、また、そのアプリケーションは指定された権限を持っている必要があります。

# Streaming APIについて
Socket.ioからREST APIと同じURLに接続してください。

レスポンスは、呼び出したメッセージ名と同じメッセージ名で返却されます。

リクエストが成功したかどうかの判定はsuccessパラメータを参照してください。

## 認証方法について
接続する際のオプションに`query.applicationKey`と`query.accessKey`を付加してアクセスすると認証されます。

## 呼び出し可能なメッセージ
### 'rest' メッセージ
REST APIをストリーム上から呼び出すことが出来ます。

request.headersに`applicationKey`と`accessKey`を付加する必要はありません。

- パラメータ
  - request.method: httpメソッド
  - request.endpoint: エンドポイント
  - request.headers: httpヘッダ
  - request.body: ペイロードデータ

- リクエスト

        {
            "request": {
                "method": "get",
                "endpoint": "/users/1234hogehoge",
                "headers": {
                    "x-api-version": 1
                }
            }
        }

- レスポンス

        {
            "success": true,
            "request": {
                "method": "get",
                "endpoint": "/users/1234hogehoge",
                "headers": {
                    "x-api-version": 1
                }
            },
            "response": {
                "user": { userEntity }
            },
            "statusCode": 200
        }

### 'timeline-connect' メッセージ
各種タイムラインのストリームに接続します。
- パラメータ
  - type: タイムラインの種類 (public, home)


- リクエスト

        {
            "type": "public"
        }

- レスポンス

        {
            "success": true,
            "message": "connected public timeline"
        }

### 'timeline-disconnect' メッセージ
各種タイムラインのストリームから切断します。
- パラメータ
  - type: タイムラインの種類 (public, home)

- リクエスト

        {
            "type": "public"
        }

- レスポンス

        {
            "success": true,
            "message": "disconnected public timeline"
        }

# Group Account
自身のアカウント

## account [/account]

### アカウントの作成 [POST]

#### アクセスに必要な権限
- `accountSpecial`

+ Request (application/json)

        {
            "screenName": "hoge",
            "password": "hogehoge",
            "name": "ほげほげ",
            "description": "ぴよぴよ"
        }

+ Response 200
    [users/id][]

# Group Applications
連携アプリケーション

## applications [/applications]

+ Model (application/json)

        {
            "applications": [{
                "createdAt": 1490034577,
                "creatorId": "58d01f91eaac651378b79b72",
                "description": "テスト用のアプリケーションです。",
                "id": "58d01f91eaac651378b79b73",
                "name": "Frost TestA",
                "permissions": [
                    "accountRead",
                    "userRead",
                    "postRead",
                    "postWrite"
                ]
            },
            {
                "createdAt": 1490034578,
                "creatorId": "58d01f91eaac651378b79b72",
                "description": "テスト用のアプリケーションです。",
                "id": "58d01f91eaac651378b79b74",
                "name": "Frost TestB",
                "permissions": [
                    "postWrite"
                ]
            }]
        }

### アプリケーションの作成 [POST]

#### アクセスに必要な権限
- `applicationSpecial`

+ Request (application/json)

        {
            "name": "Test",
            "description": "テスト用のアプリケーションです。",
            "permissions": [
                "accountRead",
                "userRead",
                "postRead",
                "postWrite"
            ]
        }

+ Response 200
    [applications/id][]

### 作成したすべてのアプリケーション情報の取得 [GET]

#### アクセスに必要な権限
- `application`

+ Response 200
    [applications][]

## applications/id [/applications/{id}]

+ Model (application/json)

        {
            "application": {
                "createdAt": 1490034577,
                "creatorId": "58d01f91eaac651378b79b72",
                "description": "テスト用のアプリケーションです。",
                "id": "58d01f91eaac651378b79b73",
                "name": "Frost Test",
                "permissions": [
                    "accountRead",
                    "userRead",
                    "postRead",
                    "postWrite"
                ]
            }
        }

+ Parameters
    + id: `58d01f91eaac651378b79b73` (string, required) - アプリケーションID。

### アプリケーション情報の取得 [GET]

#### アクセスに必要な権限
- `application`

+ Response 200
    [applications/id][]

## applications/id/application_key [/applications/{id}/application_key]

+ Model (application/json)

        {
            "applicationKey": "58d01f91eaac651378b79b73-aa9870bd22dbfbed956419994824b8498556e8f568bca86fcbd8bc41eb04151a.67654"
        }

+ Parameters
    + id: `58d01f91eaac651378b79b73` (string, required) - アプリケーションID。

### アプリケーションキーの作成 [POST]

#### アクセスに必要な権限
- `applicationSpecial`

+ Response 200
    [applications/id/application_key][]

### アプリケーションキーの取得 [GET]

#### アクセスに必要な権限
- `applicationSpecial`

+ Response 200
    [applications/id/application_key][]

# Group IceAuth
アプリケーションの認証

## ice_auth [/ice_auth]

### IceAuthキーの作成 [POST]
#### 説明
認証を行う際に必要となります。
#### アクセスに必要な権限
- 不要

+ Request (application/json)

        {
            "applicationKey": "abcdef123456abcdef123456-ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234.123"
        }

+ Response 200 (application/json)

        {
            "iceAuthKey" : "abcdef123456abcdef123456-ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234.123"
        }

## ice_auth/authorize [/ice_auth/authorize]

### 検証コード認証によるアクセスキーの作成 [POST]
#### アクセスに必要な権限
- 不要

+ Request (application/json)

    + Headers

            X-Ice-Auth-Key: abcdef123456abcdef123456-ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234.123

    + Body

            {
                "verificationCode" : "1234567890"
            }

+ Response 200

        {
            "accessKey": "58d01f91eaac651378b79b73-aa9870bd22dbfbed956419994824b8498556e8f568bca86fcbd8bc41eb04151a.67654"
        }

## ice_auth/verification_code [/ice_auth/verification_code]

### 検証コードの取得 [GET]
#### 説明
認証ホスト(Frost-Webなど)向けです。

クライアントは`ice_auth_host`権限を持つ認証ホスト上で手続きを行い、間接的に`verificationKey`を得る必要があります。
#### アクセスに必要な権限
- `iceAuthHost`

+ Request (application/json)

    + Headers

            X-Ice-Auth-Key: abcdef123456abcdef123456-ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234.123

+ Response 200 (application/json)

        {
            "verificationCode" : "1234567890"
        }

## ice_auth/target_user [/ice_auth/target_user]

### 検証コード認証の対象ユーザーの設定 [POST]
#### 説明
認証ホスト(Frost-Webなど)向けです。

`iceAuthHost`権限を持つ認証ホストが手続きを行う際に、認証の対象となったユーザーの`userId`をパラメータに付加してリクエストします。
#### アクセスに必要な権限
- `iceAuthHost`

+ Request (application/json)

    + Headers

            X-Ice-Auth-Key: abcdef123456abcdef123456-ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234.123

    + Body

            {
                "userId": "abcdef123456abcdef123457"
            }

+ Response 200 (application/json)

        {
            "targetUserId" : "abcdef123456abcdef123457"
        }

## ice_auth/authorize_basic [/ice_auth/authorize_basic]

### screenName/password認証によるアクセスキーの作成 [POST]
認証ホスト(Frost-Webなど)向けです。
#### アクセスに必要な権限
- `iceAuthHost`

+ Request (application/json)

    + Headers

            X-Ice-Auth-Key: abcdef123456abcdef123456-ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234.123

    + Body

            {
                "screenName" : "hogehoge",
                "password": "piyopiyo"
            }

+ Response 200

        {
            "accessKey": "58d01f91eaac651378b79b73-aa9870bd22dbfbed956419994824b8498556e8f568bca86fcbd8bc41eb04151a.67654"
        }

# Group Posts
投稿記事

## posts/id [/posts/{id}]

+ Parameters
    + id: `abcdef123456abcdef123456` (string, required) - ポストID。

### ポストの取得 [GET]

#### アクセスに必要な権限
- `postRead`

+ Response 200
    [posts/post_status][]

+ Response 200
    [posts/post_article][]

+ Response 200
    [posts/post_link][]

## posts/post_status [/posts/post_status]

+ Model (application/json)

        {
            "postStatus": {
                "id": "abcdef123456abcdef123456",
                "createdAt": 1234567891,
                "userId": "1",
                "text": "hogehoge"
            }
        }

### ステータスポストの作成 [POST]

#### アクセスに必要な権限
- `postWrite`

+ Request (application/json)

        {
            "text": "hogehoge"
        }

+ Response 200
    [posts/post_status][]

## posts/post_article [/posts/post_article]

+ Model (application/json)

        {
            "postArticle": {
                "id": "abcdef123456abcdef123457",
                "createdAt": 1234567892,
                "userId": "1",
                "title": "hoge",
                "description": "description text",
                "body": "hogehoge",
                "thumbnailUrl": "http://hogehoge.jp/thumbnail.png"
            }
        }

### アーティクルポストの作成 [POST]

#### アクセスに必要な権限
- `postWrite`

+ Request (application/json)

        {
            "title": "hoge",
            "description": "description text",
            "body": "hogehoge",
            "thumbnailUrl": "http://hogehoge.jp/thumbnail.png"
        }

+ Response 200
    [posts/post_article][]

## posts/post_link [/posts/post_link]

+ Model (application/json)

        {
            "postLink": {
                "id": "abcdef123456abcdef123458",
                "createdAt": 1234567893,
                "userId": "2",
                "targetPostId": "abcdef123456abcdef123458",
                "targetPost": {
                    "postArticle": {
                        "id": "abcdef123456abcdef123457",
                        "createdAt": 1234567892,
                        "userId": "1",
                        "title": "hoge",
                        "description": "description text",
                        "body": "hogehoge",
                        "thumbnailUrl": "http://hogehoge.jp/thumbnail.png"
                    }
                }
            }
        }

### リンクポストの作成 [POST]

#### アクセスに必要な権限
- `postWrite`

+ Request (application/json)

        {
            "targetPostId": "abcdef123456abcdef123458"
        }

+ Response 200
    [posts/post_link][]

# Group Users
ユーザー

## users [/users?{screen_names}=screenName1,screenName2]

+ Model (application/json)

        {
            "users": [
                {
                    "id": "abcdef123456abcdef123456",
                    "createdAt": 1234567890,
                    "screenName": "screenName1",
                    "name": "ほげほげ",
                    "description": "ぴよぴよ"
                },
                {
                    "id": "abcdef123456abcdef123457",
                    "createdAt": 1234567891,
                    "screenName": "screenName2",
                    "name": "ほげほげ",
                    "description": "ぴよぴよ"
                }
            ]
        }

### 一つ以上のscreenNameからユーザー情報を取得 [GET]

#### アクセスに必要な権限
- `userRead`

+ Parameters
    + screen_names: `screenName1,screenName2` (string, required) - ユーザー名。

+ Response 200
    [users][]

## users/id [/users/{id}]

+ Model (application/json)

        {
            "user": {
                "id": "abcdef123456abcdef123456",
                "createdAt": 1234567890,
                "screenName": "hoge",
                "name": "ほげほげ",
                "description": "ぴよぴよ"
            }
        }

+ Parameters
    + id: `abcdef123456abcdef123456` (string, required) - ユーザーID。

### ユーザー情報の取得 [GET]

#### アクセスに必要な権限
- `userRead`

+ Response 200
    [users/id][]

## users/id/timeline [/users/{id}/timeline]

+ Model (application/json)

        [
            {
                "postStatus": {
                    "id": "abcdef123456abcdef123456",
                    "createdAt": 1234567891,
                    "userId": "1",
                    "text": "hogehoge"
                }
            },
            {
                "postArticle": {
                    "id": "abcdef123456abcdef123457",
                    "createdAt": 1234567892,
                    "userId": "1",
                    "title": "hoge",
                    "description": "description text",
                    "body": "hogehoge",
                    "thumbnailUrl": "http://hogehoge.jp/thumbnail.png"
                }
            },
            {
                "postLink": {
                    "id": "abcdef123456abcdef123458",
                    "createdAt": 1234567893,
                    "userId": "2",
                    "targetPostId": "abcdef123456abcdef123458",
                    "targetPost": {
                        "postArticle": {
                            "id": "abcdef123456abcdef123457",
                            "createdAt": 1234567892,
                            "userId": "1",
                            "title": "hoge",
                            "description": "description text",
                            "body": "hogehoge",
                            "thumbnailUrl": "http://hogehoge.jp/thumbnail.png"
                        }
                    }
                }
            }
        ]

### 指定ユーザーのタイムラインの取得 [GET]

#### アクセスに必要な権限
- `userRead`, `postRead`

+ Request (application/json)

        {
            "filter": "all",
            "limit": 3
        }

+ Response 200
    [users/id/timeline][]

## users/id/followings [/users/{id}/followings]

### 指定ユーザーのフォローリストの取得 [GET]

#### アクセスに必要な権限
- `userRead`

+ Response 200

## users/id/followers [/users/{id}/followers]

### 指定ユーザーのフォロワーリストの取得 [GET]

#### アクセスに必要な権限
- `userRead`

+ Response 200

## users/id/follow [/users/{id}/follow]

### 指定ユーザーをフォロー [POST]

#### アクセスに必要な権限
- `userWrite`

+ Response 200

### 指定ユーザーへのフォローを解除 [DELETE]

#### アクセスに必要な権限
- `userWrite`

+ Response 200