ランサーズ（Lancers）エンジニアブログ > DevOps > ランサーズのメッセージ機能のAPI設計

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

blog_admin｜2019年06月10日
DevOps

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を参考にさせていただきました。そちらもぜひ参考にしてみてください。

関連記事

  1. ランサーズの仕事を機械学習で分類する – 2. 分かち書き –
  2. ぼくの考えた最強の WebAPI のエラーレスポンス型(仮)の mson を発表します!!1
  3. React Redux を用いた SPA 新規サービスを運用して得た知見と実装例
  4. ハイパフォーマンスな開発合宿をする3つの秘訣