ランサーズ等のサービスを開発・運用する中で得た知識やノウハウを紹介しています。

thumbnail

Labels:  DevOps 投稿者:ota

ランサーズのメッセージ機能のAPI設計

otaです。過去の執筆記事はこちら
ランサーズのメッセージ機能のAPIを2019年5月にリニューアルしました。どのような設計にしたかについて書きます。APIを設計する際の参考になれば幸いです。

レスポンスについて

HTTPステータスコードは成功時は200、失敗時は400を返すようにしています。失敗時には下記のレスポンスボディを返すようにしています。

{
    "type": "bad_request",
    "message": "不正なアクセスです"
}

type、messageの値は状況によって変えています。

エンドポイント一覧

実際のエンドポイントは下記以外のもの、若干異なるものもあります。汎用的に参考になりそうな部分に限っての抜粋です。ボードというのはSlackで言うところのチャンネル、Chatworkで言うところのルームです。

GET https://www.lancers.jp/message_api/v2/boards ボードの一覧を取得する

GET https://www.lancers.jp/message_api/v2/boards/unread 未読のメッセージがあるボードの一覧を取得する

POST https://www.lancers.jp/message_api/v2/boards ボードを作成する

GET https://www.lancers.jp/message_api/v2/boards/{board_id} ボードIDからボード情報取得する

PUT https://www.lancers.jp/message_api/v2/boards/{board_id} ボード情報を編集する

GET https://www.lancers.jp/message_api/v2/boards/{board_id}/users ボードに所属するユーザーの一覧を取得する

POST https://www.lancers.jp/message_api/v2/boards/{board_id}/users ボードにユーザーを追加する

DELETE https://www.lancers.jp/message_api/v2/boards/{board_id}/users/{name} ボードからユーザーを削除する

GET https://www.lancers.jp/message_api/v2/boards/{board_id}/messages ボードIDからメッセージの一覧を取得する

POST https://www.lancers.jp/message_api/v2/boards/{board_id}/messages メッセージを送信する

GET https://www.lancers.jp/message_api/v2/boards/{board_id}/files ボードに紐づくファイル一覧を取得する

PUT https://www.lancers.jp/message_api/v2/boards/{board_id}/messages/read 既読にする

GET https://www.lancers.jp/message_api/v2/boards/search 検索する

エンドポイント詳細

実際のエンドポイント、レスポンスボディは下記に含まれないもの、若干異なるものもあります。汎用的に参考になりそうな部分に限っての抜粋です。

GET https://www.lancers.jp/message_api/v2/boards

ボードの一覧を取得する

Request

Header Content-Type: application/json
Parameters

Name Type Required Default Description Example
limit int false 1 取得数 20
modified datetime false 指定した日時よりもボードの更新日時が古いものを取得する 2019-05-01 09:00:00

Response

Header Content-Type: application/json
Body

[
    {
        "id": int,
        "title": string,
        "created": datetime,
        "modified": datetime,
        "users": [
            {
                "name": string
            },
        ],
        "message": string,
        "unread_count": int,
        "unread_mention_count": int
    }
]

Example body

[
    {
        "id": 4367792,
        "title": "aliceさん,bobさんとのメッセージ",
        "created": "2019-05-17 15:27:53",
        "modified": "2019-05-17 15:28:12",
        "users": [
            {
                "name": "alice"
            },
            {
                "name": "bob"
            }
        ],
        "message": "ほげ",
        "unread_count": 0,
        "unread_mention_count": 0
    },
    {
        "id": 4367789,
        "title": "Webサイトの構築に関して",
        "created": "2019-05-16 18:28:30",
        "modified": "2019-05-16 19:36:03",
        "users": [
            {
                "name": "alice",
            },
            {
                "name": "carol",
            }
        ],
        "message": "ほげ",
        "unread_count": 2,
        "unread_mention_count": 1
    }
]

GET https://www.lancers.jp/message_api/v2/boards/unread

未読のメッセージがあるボードの一覧を取得する

Request

Header Content-Type: application/json
Parameters

Name Type Required Default Description Example
limit int false 1 ボードの取得数 20
modified datetime false null 指定日時よりも更新日時が古いボードを取得する 2019-04-22 01:18:37

Response

Header Content-Type: application/json
Body

[
    {
        "id": int,
        "board_id": int,
        "description": string,
        "status": string,
        "created": datetime,
        "modified": datetime,
        "files": array,
        "send_user": {
            "name": string
        },
        "read_users": array
    }
]

Example body

[
    {
        "id": 21995612,
        "board_id": 4367793,
        "description": "ほげ",
        "status": "ok",
        "created": "2019-05-20 14:13:37",
        "modified": "2019-05-20 14:13:37",
        "files": [],
        "send_user": {
            "name": "alice",
        },
        "read_users": [
            "alice"
        ]
    },
    {
        "id": 21995613,
        "board_id": 4367793,
        "description": "ほげ",
        "status": "ok",
        "created": "2019-05-20 14:14:03",
        "modified": "2019-05-20 14:14:03",
        "files": [
            {
                "id": 18960266,
                "name": "screenshot.png",
                "type": "image/png",
                "size": "87521",
                "comment": null,
                "created": "2019-05-20 14:14:04",
                "modified": "2019-05-20 14:14:04"
            }
        ],
        "send_user": {
            "name": "dave",
        },
        "read_users": [
            "alice", "carol"
        ]
    }
]

POST https://www.lancers.jp/message_api/v2/boards

ボードを作成する

Request

Header Content-Type: multipart/form-data
Parameters

Name Type Required Default Description Example
users array true ボードに追加するユーザーを指定する [“alice”,”bob”]
title string false nameさん,nameさんとのメッセージ ボードのタイトル aliceさん,bobさんとのメッセージ
message[‘description’] string false メッセージ文 はじめまして
message[‘files’] array false ファイル

Response

Header Content-Type: application/json
Body

{
    "id": int,
    "title": string,
    "description": null,
    "created": "2019-05-16 17:51:40",
    "modified": "2019-05-16 17:51:40",
    "owner": {
        "name": string,
    },
    "with": array
}

Example body

{
    "id": 4367787,
    "title": aliceさん,bobさんとのメッセージ",
    "description": null,
    "created": "2019-05-16 17:51:40",
    "modified": "2019-05-16 17:51:40",
    "owner": {
        "name": "alice",
    },
    "with": []
}

GET https://www.lancers.jp/message_api/v2/boards/{board_id}

ボードIDからボード情報取得する

Request

Header Content-Type: application/json
Parameters: なし

Response

Header Content-Type: application/json
Body

{
    "id": int,
    "title": string,
    "description": null,
    "created": datetime,
    "modified": datetime,
    "owner": {
        "name": string,
    },
    "with": array
}

Example body

{
    "id": 210,
    "title": "イラスト入り年賀状の件",
    "description": null,
    "created": "2008-12-22 19:56:11",
    "modified": "2008-12-23 10:12:39",
    "owner": {
        "name": "alice",
    },
    "with": {
        "proposal": {
            "id": 24,
            "work": {
                "id": 3,
                "title": "イラスト入り年賀状の作成をお願いします。",
                "type": "competition",
                "status": "completed"
            }
        }
    }
}

PUT https://www.lancers.jp/message_api/v2/boards/{board_id}

ボード情報を編集する

Request

Header Content-Type: application/json
Parameters

Name Type Required Default Description Example
title string false ボードのタイトル aliceさん,bobさんとのメッセージ
description string false ボードの概要

Response

Header Content-Type: application/json
Body

{
    "title": string,
    "description": string,
}

Example body

{
    "title": "プロジェクトについて"
}

GET https://www.lancers.jp/message_api/v2/boards/{board_id}/users

ボードに所属するユーザーの一覧を取得する

Request

Header Content-Type: application/json
Parameters

Name Type Required Default Description Example
user int string 指定したユーザネームより大きいユーザネームを取得する alice
limit int false ユーザーの取得数を指定する。指定しなかったときは全てのユーザーを取得する。 20

Response

Header Content-Type: application/json
Body

[
    {
        "name": string
    },
]

Example body

[
    {
        "name": "alice"
    },
    {
        "name": "bob"
    }
]

POST https://www.lancers.jp/message_api/v2/boards/{board_id}/users

ボードにユーザーを追加する

Request

Header Content-Type: application/json
Parameters

Name Type Required Default Description Example
users array true ボードに追加するユーザー [“alice”, “bob”]

Response

Header Content-Type: application/json
Body

[
    {
        "name": string
    },
]

Example body

[
    {
        "name": "alice"
    },
    {
        "name": "bob"
    }
]

DELETE https://www.lancers.jp/message_api/v2/boards/{board_id}/users/{name}

ボードからユーザーを削除する

Request

Header Content-Type: application/json
Parameters: なし

Response

Header Content-Type: application/json
Body

{
    "name": string
},

Example body

{
    "name": "alice"
}

GET https://www.lancers.jp/message_api/v2/boards/{board_id}/messages

ボードIDからメッセージの一覧を取得する

Request

Header Content-Type: application/json
Parameters

Name Type Required Default Description Example
message_id int false false メッセージIDを指定する 120
direction string(next or prev) false next nextのとき指定のメッセージID以上のIDのデータを取得する。prevのとき指定のメッセージID以下のIDのデータを取得する。 next
limit int false 1 メッセージの取得数 20

Response

Header Content-Type: application/json
Body

[
    {
        "id": int,
        "board_id": int,
        "description": string,
        "status": string,
        "created": datetime,
        "modified": datetime,
        "files": array,
        "send_user": {
            "name": string
        },
        "read_users": array
    }
]

Example body

[
    {
        "id": 21995612,
        "board_id": 4367793,
        "description": "ほげ",
        "status": "ok",
        "created": "2019-05-20 14:13:37",
        "modified": "2019-05-20 14:13:37",
        "files": [],
        "send_user": {
            "name": "alice"
        },
        "read_users": [
            "alice"
        ]
    },
    {
        "id": 21995613,
        "board_id": 4367793,
        "description": "ほげ",
        "status": "ok",
        "created": "2019-05-20 14:14:03",
        "modified": "2019-05-20 14:14:03",
        "files": [
            {
                "id": 18960266,
                "name": "LWScreenShot 2019-02-04 at 10.32.30.png",
                "type": "image/png",
                "size": "87521",
                "comment": null,
                "created": "2019-05-20 14:14:04",
                "modified": "2019-05-20 14:14:04"
            }
        ],
        "send_user": {
            "name": "carol",
        },
        "read_users": [
            "alice", "bob"
        ]
    }
]

POST https://www.lancers.jp/message_api/v2/boards/{board_id}/messages

メッセージを送信する

Request

Header Content-Type: multipart/form-data
Parameters

Name Type Required Default Description Example
description string false null メッセージ文 はじめまして
files array false ファイル

Response

Header Content-Type: application/json
Body

{
    "id": int,
    "board_id": int,
    "description": string,
    "status": string,
    "created": datetime,
    "modified": datetime,
    "files": array,
    "send_user": {
        "name": string,
    },
    "read_users": array
}

Example body

{
    "id": 21995615,
    "board_id": 4367793,
    "description": "ほげ",
    "status": "ok",
    "created": "2019-05-20 14:30:57",
    "modified": "2019-05-20 14:30:57",
    "files": [
        {
            "id": 18960267,
            "name": "screenshot.png",
            "type": "image/png",
            "size": "87521",
            "comment": null,
            "created": "2019-05-20 14:30:57",
            "modified": "2019-05-20 14:30:57"
        }
    ],
    "send_user": {
        "name": "alice",
    },
    "read_users": []
}

GET https://www.lancers.jp/message_api/v2/boards/{board_id}/files

ボードに紐づくファイル一覧を取得する

Request

Header Content-Type: application/json
Parameters

Name Type Required Default Description Example
file_id int false false 指定のファイルID以上のIDのファイルを取得する 14
limit int false 1 ファイルの取得数 20

Response

Header Content-Type: application/json
Body

[
    {
        "id": int,
        "name": string,
        "type": string,
        "size": int,
        "comment": string or null,
        "created": datetime,
        "modified": datetime,
        "user": {
            "name": string
        }
    },
]

Example body

[
    {
        "id": 18960267,
        "name": "screenshot 2019-02-04 at 10.32.30.png",
        "type": "image/png",
        "size": "87521",
        "comment": null,
        "created": "2019-05-20 14:30:57",
        "modified": "2019-05-20 14:30:57",
        "user": {
            "name": "alice"
        }
    },
    {
        "id": 18960266,
        "name": "screenshot.png",
        "type": "image/png",
        "size": "87521",
        "comment": null,
        "created": "2019-05-20 14:14:04",
        "modified": "2019-05-20 14:14:04",
        "user": {
            "name": "bob"
        }
    }
]

PUT https://www.lancers.jp/message_api/v2/boards/{board_id}/messages/read

既読にする

Request

Header Content-Type: application/json
Parameters

Name Type Required Default Description Example
message_id int false null 指定のメッセージIDまで既読にする 2

Response

Header Content-Type: application/json
Body

{
    "board_id": int,
    "unread_count": int
}

Example body

{
    "board_id": "4367793",
    "unread_count": 2
}

GET https://www.lancers.jp/message_api/v2/boards/search

検索する

Request

Header Content-Type: application/json
Parameters

Name Type Required Default Description Example
q string true 検索ワード alice
offset int false 0 検索結果の取得のスタート地点 20
limit int false 20 検索結果の取得数 10

Response

Header Content-Type: application/json
Body

[
    {
        "id": int,
        "title": string,
        "created": datetime,
        "modified": datetime,
        "users": [
            {
                "name": string
            }
        ],
        "message": string,
        "unread_count": int,
        "unread_mention_count": int
    }
]

Example body

[
    {
        "id": 4332096,
        "title": "プロジェクトについて",
        "created": "2019-04-22 01:18:37",
        "modified": "2019-04-22 01:18:37",
        "users": [
            {
                "name": "alice"
            }
            {
                "name": "bob"
            }
        ],
        "message": "ほげ",
        "unread_count": 1,
        "unread_mention_count": 1
    },
    {
        "id": 4332097,
        "title": "コンペについて",
        "created": "2019-04-22 01:18:37",
        "modified": "2019-04-22 01:18:37",
        "users": [
            {
                "name": "carol"
            },
            {
                "name": "alice"
            }
        ],
        "message": "ほげ",
        "unread_count": 0,
        "unread_mention_count": 0
    }
]

以上になります。今回実装するにあたってchatwork APIドキュメントslack apiを参考にさせていただきました。そちらもぜひ参考にしてみてください。

ランサーズではサービスを成長させてくれるエンジニア、デザイナーを募集しています!
ご興味がある方は、以下URLよりご応募ください。


【中途採用】
サービスリードエンジニア
テックリード(アーキテクト)
フロントエンドエンジニア
サーバーサイドエンジニア
業務エンジニア(社内システム基盤・基幹システム)

【インターン・学生バイト】
19新卒対象サマーインターン
エンジニアインターン

その他採用情報

関連記事

thumbnail
あなたの世界

こんにちは、ランサーズのエンジニアのameshoです。 開発をしていると、隣の人と特定のコマンドなどについて話し込んだりしますよね。 この間、agやdiffについて話していて、 The Silver Searcher agってコマンドがあって乱暴に説明するとg …

thumbnail
日々の開発について

ランサーズ Advent Calendar 2016 6日目の記事です。 エンジニアのmakoです。 入社して半年経ちランサーズの開発で使用している技術について書きたいと思います。 業界として最近では使われることも多い技術や手法ですが入社前まではほとんど経験が …

新規事業開発におけるエンジニアの心得〜失敗事例から学ぶツクラナイ開発〜

tsuyoshi(@numanomanu)です。 先日、エンジニア向けのイベントで登壇して来たので、その時の資料を共有させていただきます。【サポーターズCoLab勉強会】新規事業開発におけるエンジニアの心得。 私自身、昨年、CtoCサービスの新規事業の立ち上げ …