この記事では esa API v1について説明します。
APIとの通信には HTTPS
プロトコルを使用します。アクセス先のホストは api.esa.io
です。
API v1へのリクエストには、 GET
/ POST
/ PUT
/ PATCH
/ DELETE
の HTTPメソッドを利用します。
多くのAPIはリクエスト時にパラメータを含められますが、GETリクエストにはURIクエリ文字列を利用し、それ以外の場合にはリクエストボディを利用します。パラメータにはページネーション等の任意で渡すものと、記事名等の必須のものが存在します。
現時点では、ユーザ毎に15分間に300リクエストまで受け付けます。
データのインポート等で短期間に大量のAPIリクエストを予定している場合は、チームのフィードバックフォームから「対象のチーム名」と「ご希望期間」を明記の上、一時的な制限の緩和についてご相談下さい。
制限状況はAPIのレスポンスヘッダに含まれる x-ratelimit-*
の値をご確認下さい。
x-ratelimit-limit: 300
x-ratelimit-remaining: 299
x-ratelimit-reset: 1728609300
なお、決められた制限を超える場合は、429 Too Many Requests
が返却されます。
200
/ 201
/ 204
/ 400
/ 401
/ 402
/ 403
/ 404
/ 405
/ 406
/ 409
/ 429
/ 500
のステータスコードを利用します。
APIとのデータの送受信にはJSONを利用します。JSONをリクエストボディに含める場合はContent-Type: application/json
をリクエストヘッダに追加して下さい。文字コードはUTF-8を使用して下さい。
エラーが発生した場合は、エラーを表現するオブジェクトを含んだエラーレスポンスが返却されます。
{
"error": "not_found",
"message": "Not found"
}
ステータスごとのよくある対策例を示します。
Retry after N seconds.
を参考に、指定された時間後に再度リクエストをお試しくださいリストを返すAPIでは、すべての要素を一度に返すことは現実的ではないため、ページを指定することができるようになっています。これらのAPIには、1から始まるページ番号を表す page
パラメータと、1ページあたりに含まれる要素数を表す per_page
パラメータを指定することができます。page
の初期値は 1
に設定されています。また、 per_page
の初期値は 20
、最大値は 100
に設定されています。
ページを指定できるAPIでは、ページネーションの情報を含んだレスポンスを返します。
# GET /v1/teams HTTP/1.1
{
"teams": [
...
],
"prev_page": null,
"next_page": 2,
"total_count": 30,
"page": 1,
"per_page": 20,
"max_per_page": 100
}
現時点で以下のライブラリが利用可能です。
esa APIを利用するには、アクセストークンをリクエストに含める必要があります。アクセストークンは、ユーザの管理画面(https://[team].esa.io/user/applications)もしくはOAuthを利用した認可フローにより発行できます。
アクセストークンは、以下のようにリクエストヘッダに含められます。
Authorization: Bearer 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
また、URIクエリ文字列として指定することも可能です。
api.esa.io/v1/teams?access_token=1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
個々のアクセストークンには、複数のスコープを紐付けることができます。アクセストークンが適切なスコープを持っている時のみAPIを利用することができます。esa APIでは以下のスコープを利用することができます。
スコープ | 説明 |
---|---|
read | データの読み出し |
write | データの書き込み |
https://[team].esa.io/user/applications
から アプリケーションを登録できます。
※ RailsやSinatraでは、以下の手順は omniauth-esa を使うことで実装の手間を省くことが出来ます。
アプリケーションのユーザーに認可画面を表示します。
urn:ietf:wg:oauth:2.0:oob
を指定した場合、認可後にリダイレクトせず画面に認証コードを表示しますcode
を指定しますGET /oauth/authorize?client_id=0a9bff757caf1eeb344421211637bb6cf724da767062069cafe16a43283a6e04&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code&scope=read+write&state=a7e567e2fb858f0e12838798016ee9cf8ccc778 HTTP/1.1
新規にアクセストークンを発行します。
authorization_code
を指定しますPOST /oauth/token HTTP/1.1
{"client_id":"0a9bff757caf1eeb344421211637bb6cf724da767062069cafe16a43283a6e04","client_secret":"ca6eb9452f2fdaaa68a8d870bc654db8e6f466f6d42685b914e04c442b2065a2","code":"c486e26492dfdc42bcf4e07bfbd84a97f98548c1cf89178a512e76b79b099313","grant_type":"authorization_code","redirect_uri":"urn:ietf:wg:oauth:2.0:oob"}
HTTP/1.1 200 OK
{
"access_token": "5d49aab1f0796bbbd78100f06c6cd4d667851644012d37421073bb61126cdafc",
"token_type": "Bearer",
"scope": "read write",
"created_at": 1461218696
}
アクセストークンの情報を取得します
GET /oauth/token/info HTTP/1.1
Authorization: Bearer 5d49aab1f0796bbbd78100f06c6cd4d667851644012d37421073bb61126cdafc
HTTP/1.1 200 OK
{"resource_owner_id":1,"scope":["read","write"],"expires_in":null,"application":{"uid":"0a9bff757caf1eeb344421211637bb6cf724da767062069cafe16a43283a6e04"},"created_at":1461218696,"user":{"id":1}}
アクセストークンを失効させます
POST /oauth/revoke HTTP/1.1
{"client_id":"0a9bff757caf1eeb344421211637bb6cf724da767062069cafe16a43283a6e04","client_secret":"ca6eb9452f2fdaaa68a8d870bc654db8e6f466f6d42685b914e04c442b2065a2","token":"5d49aab1f0796bbbd78100f06c6cd4d667851644012d37421073bb61126cdafc"}
HTTP/1.1 200 OK
{}
esa上で所属しているチームを表します。
""
)になりますMEMO: member_count等の情報を追加予定
member
owner
GET /v1/teams HTTP/1.1
{
"teams": [
{
"name": "docs",
"privacy": "open",
"description": "esa.io official documents",
"icon": "https://img.esa.io/uploads/production/teams/105/icon/thumb_m_0537ab827c4b0c18b60af6cdd94f239c.png",
"url": "https://docs.esa.io/"
}
],
"prev_page": null,
"next_page": null,
"total_count": 1,
"page": 1,
"per_page": 20,
"max_per_page": 100
}
GET /v1/teams/docs HTTP/1.1
{
"name": "docs",
"privacy": "open",
"description": "esa.io official documents",
"icon": "https://img.esa.io/uploads/production/teams/105/icon/thumb_m_0537ab827c4b0c18b60af6cdd94f239c.png",
"url": "https://docs.esa.io/"
}
チームの統計情報を表します。
GET /v1/teams/docs/stats HTTP/1.1
{
"members": 20,
"posts": 1959,
"posts_wip": 59,
"posts_shipped": 1900,
"comments": 2695,
"stars": 3115,
"daily_active_users": 8,
"weekly_active_users": 14,
"monthly_active_users": 15
}
チームのメンバーを表します。
posts_count
(default)
joined
last_accessed
desc
(default)
asc
GET /v1/teams/docs/members HTTP/1.1
{
"members": [
{
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "https://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png",
"role": "owner",
"posts_count": 222,
"joined_at": "2014-07-01T08:10:55+09:00",
"last_accessed_at": "2019-12-27T16:23:23+09:00",
"email": "fukayatsu@esa.io",
},
{
"myself": false,
"name": "TAEKO AKATSUKA",
"screen_name": "taea",
"icon": "https://img.esa.io/uploads/production/users/2/icon/thumb_m_2690997f07b7de3014a36d90827603d6.jpg",
"role": "owner",
"posts_count": 111,
"joined_at": "2014-07-01T08:19:26+09:00",
"last_accessed_at": "2019-08-13T18:07:24+09:00",
"email": "taea@esa.io",
}
],
"prev_page": null,
"next_page": null,
"total_count": 2,
"page": 1,
"per_page": 20,
"max_per_page": 100
}
指定したscreen_nameもしくはemailに一致するメンバーの情報を取得します。
me
を指定すると自身の情報を取得します。GET /v1/teams/docs/members/ppworks
{
"myself": true,
"name": "越川 直人",
"screen_name": "ppworks",
"icon": "https://img.esa.io/uploads/production/members/16377/icon/thumb_m_78785723178d961fcb80fff537c56d35.jpeg",
"role": "owner",
"posts_count": 84,
"joined_at": "2016-11-17T20:50:40+09:00",
"last_accessed_at": "2023-10-03T11:11:54+09:00",
"email": "ppworks@esa.io"
}
指定した screen_name もしくは email に一致するメンバーをチームから削除します。
DELETE /v1/teams/docs/members/alice HTTP/1.1
HTTP/1.1 204 No Content
ユーザが作成した記事を表します。
null
になります<h1>Getting Started</h1>
created_by
と共通です。記事の一覧を返却します
GET /v1/teams/docs/posts HTTP/1.1
comments
を指定するとコメントの配列を含んだレスポンスを返します。comments,comments.stargazers
を指定するとコメントとコメントに対するStarの配列を含んだレスポンスを返します。stargazers
を指定するとStarの配列を含んだレスポンスを返します。stargazers,comments
のように ,
で区切ることで複数指定できますupdated
(default)
created
number
stars
watches
comments
best_match
desc
(default)
asc
{
"posts": [
{
"number": 1,
"name": "hi!",
"full_name": "日報/2015/05/09/hi! #api #dev",
"wip": true,
"body_md": "# Getting Started",
"body_html": "<h1 id=\"1-0-0\" name=\"1-0-0\">\n<a class=\"anchor\" href=\"#1-0-0\"><i class=\"fa fa-link\"></i><span class=\"hidden\" data-text=\"Getting Started\"> > Getting Started</span></a>Getting Started</h1>\n",
"created_at": "2015-05-09T11:54:50+09:00",
"message": "Add Getting Started section",
"url": "https://docs.esa.io/posts/1",
"updated_at": "2015-05-09T11:54:51+09:00",
"tags": [
"api",
"dev"
],
"category": "日報/2015/05/09",
"revision_number": 1,
"created_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
},
"updated_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
}
}
],
"prev_page": null,
"next_page": null,
"total_count": 1,
"page": 1,
"per_page": 20,
"max_per_page": 100
}
指定された投稿を取得します。
comments
を指定するとコメントの配列を含んだレスポンスを返します。comments,comments.stargazers
を指定するとコメントとコメントに対するStarの配列を含んだレスポンスを返します。stargazers
を指定するとStarの配列を含んだレスポンスを返します。GET /v1/teams/docs/posts/1 HTTP/1.1
{
"number": 1,
"name": "hi!",
"full_name": "日報/2015/05/09/hi! #api #dev",
"wip": true,
"body_md": "# Getting Started",
"body_html": "<h1 id=\"1-0-0\" name=\"1-0-0\">\n<a class=\"anchor\" href=\"#1-0-0\"><i class=\"fa fa-link\"></i><span class=\"hidden\" data-text=\"Getting Started\"> > Getting Started</span></a>Getting Started</h1>\n",
"created_at": "2015-05-09T11:54:50+09:00",
"message": "Add Getting Started section",
"url": "https://docs.esa.io/posts/1",
"updated_at": "2015-05-09T11:54:51+09:00",
"tags": [
"api",
"dev"
],
"category": "日報/2015/05/09",
"revision_number": 1,
"created_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
},
"updated_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
},
"kind": "flow",
"comments_count": 1,
"tasks_count": 1,
"done_tasks_count": 1,
"stargazers_count": 1,
"watchers_count": 1,
"star": true,
"watch": true
}
記事を新たに投稿します。
#
を含めたい場合は#
, /
を含めたい場合は/
へそれぞれ置換処理をお願いします。POST /v1/teams/docs/posts HTTP/1.1
Content-Type: application/json
{
"post":{
"name":"hi!",
"body_md":"# Getting Started\n",
"tags":[
"api",
"dev"
],
"category":"dev/2015/05/10",
"wip":false,
"message":"Add Getting Started section"
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"number": 5,
"name": "hi!",
"full_name": "dev/2015/05/10/hi! #api #dev",
"wip": false,
"body_md": "# Getting Started\n",
"body_html": "<h1 id=\"1-0-0\" name=\"1-0-0\">\n<a class=\"anchor\" href=\"#1-0-0\"><i class=\"fa fa-link\"></i><span class=\"hidden\" data-text=\"Getting Started\"> > Getting Started</span></a>Getting Started</h1>\n",
"created_at": "2015-05-09T12:12:37+09:00",
"message": "Add Getting Started section",
"url": "https://docs.esa.io/posts/5",
"updated_at": "2015-05-09T12:12:37+09:00",
"tags": [
"api",
"dev"
],
"category": "dev/2015/05/10",
"revision_number": 1,
"created_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
},
"updated_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
},
"kind": "flow",
"comments_count": 0,
"tasks_count": 0,
"done_tasks_count": 0,
"stargazers_count": 0,
"watchers_count": 1,
"star": false,
"watch": false
}
指定された投稿を編集します。
リクエストに正常な post.body_md
パラメータと post.original_revision.*
パラメータが存在する場合、記事更新時に3 way mergeが行われます。original_revisionパラメータが存在しない場合は、変更は常に後勝ちになります。
PATCH /v1/teams/docs/posts/5 HTTP/1.1
Content-Type: application/json
{
"post":{
"name":"hi!",
"body_md":"# Getting Started\n",
"tags":[
"api",
"dev"
],
"category":"dev/2015/05/10",
"wip":false,
"message":"Add Getting Started section",
"original_revision": {
"body_md": "# Getting ...",
"number":1,
"user": "fukayatsu"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"number": 5,
"name": "hi!",
"full_name": "日報/2015/05/10/hi! #api #dev",
"wip": false,
"body_md": "# Getting Started\n",
"body_html": "<h1 id=\"1-0-0\" name=\"1-0-0\">\n<a class=\"anchor\" href=\"#1-0-0\"><i class=\"fa fa-link\"></i><span class=\"hidden\" data-text=\"Getting Started\"> > Getting Started</span></a>Getting Started</h1>\n",
"created_at": "2015-05-09T12:12:37+09:00",
"message": "Add Getting Started section",
"url": "https://docs.esa.io/posts/5",
"updated_at": "2015-05-09T12:19:48+09:00",
"tags": [
"api",
"dev"
],
"category": "日報/2015/05/10",
"revision_number": 2,
"created_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
},
"updated_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
},
"overlapped": false,
"kind": "flow",
"comments_count": 0,
"tasks_count": 0,
"done_tasks_count": 0,
"stargazers_count": 0,
"watchers_count": 1,
"star": false,
"watch": false
}
true
になります。指定された投稿を削除します。
DELETE /v1/teams/docs/posts/5 HTTP/1.1
HTTP/1.1 204 No Content
ユーザが作成したコメントを表します。
LGTM!
<p>LGTM!</p>
2014-05-10T12:45:42+09:00
2014-05-18T23:02:29+09:00
記事のコメント一覧を更新日の降順で返却します。
GET /v1/teams/docs/posts/2/comments HTTP/1.1
{
"comments": [
{
"id": 1,
"body_md": "(大事)",
"body_html": "<p>(大事)</p>",
"created_at": "2014-05-10T12:45:42+09:00",
"updated_at": "2014-05-18T23:02:29+09:00",
"url": "https://docs.esa.io/posts/2#comment-1",
"created_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "https://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
},
"stargazers_count": 0,
"star": false
}
],
"prev_page": null,
"next_page": null,
"total_count": 1,
"page": 1,
"per_page": 20,
"max_per_page": 100
}
指定されたコメントを取得します。
GET /v1/teams/docs/comments/13 HTTP/1.1
stargazers
を指定するとStarの配列を含んだレスポンスを返します。{
"id": 13,
"body_md": "読みたい",
"body_html": "<p>読みたい</p>",
"created_at": "2014-05-13T16:17:42+09:00",
"updated_at": "2014-05-18T23:02:29+09:00",
"url": "https://docs.esa.io/posts/13#comment-13",
"created_by": {
"myself": false,
"name": "TAEKO AKATSUKA",
"screen_name": "taea",
"icon": "https://img.esa.io/uploads/production/users/2/icon/thumb_m_2690997f07b7de3014a36d90827603d6.jpg"
},
"stargazers_count": 0,
"star": false
}
記事に新しいコメントを作成します。
POST /v1/teams/docs/posts/2/comments HTTP/1.1
Content-Type: application/json
{"comment":{"body_md":"LGTM!"}}
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": 22767,
"body_md": "LGTM!",
"body_html": "<p>LGTM!</p>\n",
"created_at": "2015-06-21T19:36:20+09:00",
"updated_at": "2015-06-21T19:36:20+09:00",
"url": "https://docs.esa.io/posts/2#comment-22767",
"created_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "https://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
},
"stargazers_count": 0,
"star": false
}
指定されたコメントを更新します。
PATCH /v1/teams/docs/comments/22767 HTTP/1.1
Content-Type: application/json
{"comment":{"body_md":"LGTM!!!"}}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 22767,
"body_md": "LGTM! :sushi:",
"body_html": "<p>LGTM!!!</p>\n",
"created_at": "2015-06-21T19:36:20+09:00",
"updated_at": "2015-06-21T19:40:33+09:00",
"url": "https://docs.esa.io/posts/2#comment-22767",
"created_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "https://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
},
"stargazers_count": 0,
"star": false
}
指定されたコメントを削除します。
DELETE /v1/teams/docs/comments/22767 HTTP/1.1
HTTP/1.1 204 No Content
チーム全体のコメント一覧を作成日の降順で返却します。
GET /v1/teams/docs/comments HTTP/1.1
{
"comments": [
{
"id": 1,
"body_md": "(大事)",
"body_html": "<p>(大事)</p>",
"created_at": "2014-05-10T12:45:42+09:00",
"updated_at": "2014-05-18T23:02:29+09:00",
"url": "https://docs.esa.io/posts/2#comment-1",
"created_by": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "https://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
},
"stargazers_count": 0,
"star": false
}
],
"prev_page": null,
"next_page": null,
"total_count": 1,
"page": 1,
"per_page": 20,
"max_per_page": 100
}
指定された記事にStarをしたユーザ一覧を取得します。
GET /v1/teams/docs/posts/2312/stargazers HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"stargazers": [
{
"created_at": "2016-05-05T11:40:54+09:00",
"body": null,
"user": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "https://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
}
}
],
"prev_page": null,
"next_page": null,
"total_count": 1,
"page": 1,
"per_page": 20,
"max_per_page": 100
}
指定された記事にStarをします。
POST /v1/teams/docs/posts/2312/star HTTP/1.1
{"body":"foo bar"}
HTTP/1.1 204 No Content
指定された記事へのStarを取り消します。
DELETE /v1/teams/docs/posts/2312/star HTTP/1.1
HTTP/1.1 204 No Content
指定されたコメントにStarをしたユーザ一覧を取得します。
GET /v1/teams/docs/comments/123/stargazers HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"stargazers": [
{
"created_at": "2016-05-05T11:40:54+09:00",
"body": null,
"user": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "https://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
}
}
],
"prev_page": null,
"next_page": null,
"total_count": 1,
"page": 1,
"per_page": 20,
"max_per_page": 100
}
指定されたコメントにStarをします。
POST /v1/teams/docs/comments/123/star HTTP/1.1
{"body":"foo bar"}
HTTP/1.1 204 No Content
指定されたコメントへのStarを取り消します。
DELETE /v1/teams/docs/comments/123/star HTTP/1.1
HTTP/1.1 204 No Content
指定された記事にWatchをしたユーザ一覧を取得します。
GET /v1/teams/docs/posts/2312/watchers HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"watchers": [
{
"created_at": "2016-05-05T11:40:53+09:00",
"user": {
"myself": true,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"icon": "https://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
}
}
],
"prev_page": null,
"next_page": null,
"total_count": 1,
"page": 1,
"per_page": 20,
"max_per_page": 100
}
指定された記事にWatchをします。
POST /v1/teams/docs/posts/2312/watch HTTP/1.1
HTTP/1.1 204 No Content
指定された記事のWatchを取り消します。
DELETE /v1/teams/docs/posts/2312/watch HTTP/1.1
HTTP/1.1 204 No Content
指定されたカテゴリを配下のカテゴリを含めて一括で変更します。
POST /v1/teams/docs/categories/batch_move HTTP/1.1
{
"from": "/foo/bar/",
"to": "/baz/"
}
HTTP/1.1 200 OK
{
"count": 3,
"from": "/foo/bar/",
"to": "/baz/"
}
タグ一覧をタグ付けされた記事数の降順で返却します。
GET /v1/teams/docs/tags HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"tags": [
{
"name": "noexpand",
"posts_count": 6
},
{
"name": "ChromeExtension",
"posts_count": 2
},
{
"name": "rubykaigi",
"posts_count": 2
},
{
"name": "stock",
"posts_count": 2
},
{
"name": "markdown",
"posts_count": 2
},
{
"name": "yapcasiaA",
"posts_count": 1
},
{
"name": "tqrk09",
"posts_count": 1
},
{
"name": "idobata_io",
"posts_count": 1
},
{
"name": "RBUC",
"posts_count": 1
},
{
"name": "hcmpl",
"posts_count": 1
},
{
"name": "railsdm",
"posts_count": 1
},
{
"name": "消費税",
"posts_count": 1
},
{
"name": "tags",
"posts_count": 1
},
{
"name": "editor",
"posts_count": 1
},
{
"name": "仕様変更",
"posts_count": 1
},
{
"name": "yapcasia",
"posts_count": 1
}
],
"prev_page": null,
"next_page": null,
"total_count": 16,
"page": 1,
"per_page": 1000,
"max_per_page": 1000
}
チームへの招待URLを取得します。
このAPIは team の owner だけがご利用可能です。
GET /v1/teams/docs/invitation HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"url": "https://docs.esa.io/team/invitations/member-c05d112fa34870998ab4da1e98846ae3"
}
チームへの招待URLを再発行します。
このAPIは team の owner だけがご利用可能です。
POST /v1/teams/docs/invitation_regenerator HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"url": "https://docs.esa.io/team/invitations/member-58891f72edcbb8ac22f1e5548b0128d9"
}
招待したいメンバーへ個別の招待URLを発行し、指定したEメールアドレスへ送信します。
このAPIは team の owner だけがご利用可能です。
POST /v1/teams/:team_name/invitations HTTP/1.1
Content-Type: application/json
{
"member": {
"emails": ["foo@example.com", "bar@example.com"]
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"invitations": [
{
"email": "foo@example.com",
"code": "mee93383edf699b525e01842d34078e28",
"expires_at": "2017-08-17T12:00:41+09:00",
"url": "https://docs.esa.io/team/invitations/mee93383edf699b525e01842d34078e28/join"
},
{
"email": "bar@example.com",
"code": "m934f1f60732f49d50ee5b3f96841ff13",
"expires_at": "2017-08-17T12:00:41+09:00",
"url": "https://docs.esa.io/team/invitations/m934f1f60732f49d50ee5b3f96841ff13/join"
}
]
}
招待中のメンバーの一覧を取得します。
このAPIは team の owner だけがご利用可能です。
GET /v1/teams/:team_name/invitations HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"invitations": [
{
"email": "foo@example.com",
"code": "mee93383edf699b525e01842d34078e28",
"expires_at": "2017-08-17T12:00:41+09:00",
"url": "https://docs.esa.io/team/invitations/mee93383edf699b525e01842d34078e28/join"
},
{
"email": "bar@example.com",
"code": "mc542eed211a8e4f1db6ccccb14fcda9d",
"expires_at": "2017-08-17T12:00:44+09:00",
"url": "https://docs.esa.io/team/invitations/mc542eed211a8e4f1db6ccccb14fcda9d/join"
}
],
"prev_page": null,
"next_page": null,
"total_count": 2,
"page": 1,
"per_page": 20,
"max_per_page": 100
}
招待中のメンバーの招待を削除します。招待時に送信されたメールに記載された招待用のURLは無効となります。
このAPIは team の owner だけがご利用可能です。
DELETE /v1/teams/:team_name/invitations/mee93383edf699b525e01842d34078e28 HTTP/1.1
HTTP/1.1 204 No Content
NULL
になりますチームで利用可能な絵文字を取得します。URIクエリ文字列を含めない場合、チーム固有の絵文字だけを取得します。
GET /v1/teams/docs/emojis HTTP/1.1
all
を指定すると、チーム固有の絵文字だけではなく、すべての絵文字を返します。HTTP/1.1 200 OK
Content-Type: application/json
{
"emojis": [
{
"code": "grinning",
"aliases": [
"grinning"
],
"category": "Smileys & Emotion",
"raw": "😀",
"url": "https://assets.esa.io/images/emoji/unicode/1f600.png"
},
{
"code": "smiley",
"aliases": [
"smiley"
],
"category": "Smileys & Emotion",
"raw": "😃",
"url": "https://assets.esa.io/images/emoji/unicode/1f603.png"
},
// ...省略...
]
}
新しい絵文字を登録します。
POST /v1/teams/docs/emojis HTTP/1.1
Content-Type: application/json
{
"emoji": {
"code": "team_emoji",
"image": "..." // BASE64 String
}
}
HTTP/1.1 201 Created
{
"code": "team_emoji"
}
POST /v1/teams/docs/emojis HTTP/1.1
Content-Type: multipart/form-data; boundary=------TestBoundaryi123456789
------TestBoundaryi123456789
Content-Disposition: form-data; name="emoji[code]"
team_emoji
------TestBoundaryi123456789
Content-Disposition: form-data; name="emoji[image]"; filename="emoji.png"
Content-Type: image/png
PNG
// ...省略...
登録したチーム固有の絵文字を削除します。
DELETE /v1/teams/docs/emojis/team_emoji
HTTP/1.1 204 No Content
現在のアクセストークンで認証中のユーザの情報を表します。
teams
を指定すると所属するチームの配列を含んだレスポンスを返します。GET /v1/user HTTP/1.1
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1,
"name": "Atsuo Fukaya",
"screen_name": "fukayatsu",
"created_at": "2014-05-10T11:50:07+09:00",
"updated_at": "2016-04-17T12:35:16+09:00",
"icon": "https://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png",
"email": "fukayatsu@esa.io"
}
Qiita Teamからのインポート機能をご利用ください。
require 'esa'
require 'json'
require 'pp'
require 'pry'
class Importer
def initialize(client, wiki_repo_url)
@client = client
`git clone #{wiki_repo_url} wiki_data` unless File.exist? 'wiki_data'
Dir.chdir('wiki_data')
@file_names = Dir.glob('*.md')
end
attr_accessor :client, :file_names
def wait_for(seconds)
(seconds / 10).times do
print '.'
sleep 10
end
puts
end
def import(dry_run: true)
file_names.each do |file_name|
title = File.basename(file_name)
params = {
name: title,
category: "Imports/GitHubWiki",
body_md: File.read(file_name),
wip: false,
message: '[skip notice] Imported from GitHub Wiki',
user: 'esa_bot' # 記事作成者上書き: owner権限が必要
}
if dry_run
pp params
puts
next
end
print "[#{Time.now}] #{title} => "
response = client.create_post(params)
case response.status
when 201
puts "created: #{response.body["full_name"]}"
when 429
retry_after = (response.headers['Retry-After'] || 20 * 60).to_i
puts "rate limit exceeded: will retry after #{retry_after} seconds."
wait_for(retry_after)
redo
else
puts "failure with status: #{response.status}"
exit 1
end
end
end
end
client = Esa::Client.new(
access_token: 'xxxxx',
current_team: 'your-team-name' # 移行先のチーム名(サブドメイン)
)
importer = Importer.new(client, 'https://github.com/[organization]/[repo].wiki.git')
# dry_run: trueで確認後に dry_run: falseで実際にimportを実行
importer.import(dry_run: true)