Link Search Menu Expand Document

REST API

外部のアプリケーションからkickflowを操作するREST API

Table of contents

  1. エンドポイント
  2. 各APIの詳細
  3. 認証
  4. Role-based Access Control (RBAC)
  5. ページネーション
  6. ソート
  7. 利用制限
  8. オリジン間リソース共有(CORS)
  9. タイムゾーン
  10. エラー

エンドポイント

  • https://api.kickflow.com/v1/
    • Content-Type: application/jsonのみ許可します

各APIの詳細

各APIの仕様はこちらからご確認ください。

また、OpenAPI 3.0の定義ファイルはこちらからダウンロードできます。

認証

アクセストークンによる認証を行います。アクセストークン設定画面から発行したアクセストークンを、下記の形式でAuthorizationヘッダーに設定してください。

Authorization: Bearer YOUR_ACCESS_TOKEN

認証に失敗した場合、REST APIは401 Unauthorizedを返却します。

Role-based Access Control (RBAC)

kickflowではユーザーの管理権限をRBACで管理しています。 アクセストークンに紐づくアクセス権限は、RBACによってユーザーが持つ権限に一致します。 ユーザーが権限を持たないAPIを実行した場合、kickflowは403 Forbiddenを返却します。

ページネーション

一部のAPIではページネーションが可能です。 ページネーションが可能なAPIでは、pageperPageをクエリパラメータに追加することで、指定したページのデータを取得することができます。

  • pageは1が最初のページを表します(0ではないことに注意してください)。設定しない場合、page=1とみなします。
  • perPageはデフォルト値は25で、最大100まで設定可能です。

レスポンスにはRFC-5988によるLinkヘッダーが付加されます。

Link: <https://api.kickflow.com/v1/users?page=2&perPage=100>; rel="next",
  <https://api.kickflow.com/v1/users?page=50&perPage=100>; rel="last"

ソート

一部のAPIではソートが可能です。 ソートが可能なAPIでは、クエリパラメータにsortBy=[フィールド名]-[asc|desc]を付けることで、ソート対象のフィールドと昇順・降順を指定できます。

例えば、ユーザー一覧を取得するAPIの場合以下のようになります。

# メールアドレスで昇順
/v1/users?sortBy=email-asc

# メールアドレスで降順
/v1/users?sortBy=email-desc

APIによってソート可能なフィールドは限定されています。選択不可能なフィールドをクエリで指定した場合、そのクエリは無視されます。

利用制限

リクエスト元のIPアドレスごとに毎分30回までREST APIを実行可能です。これを超えた場合、kickflowはレスポンスとして429 Too Many Requestsを返します。

ユーザーが利用制限を回避できるようにするため、kickflowはレスポンスに下記のヘッダーを付加します。

ヘッダー 説明
RateLimit-Limit 単位時間あたりの実行回数上限
RateLimit-Remaining 現在のウィンドウ内での残り実行可能回数
RateLimit-Reset ウィンドウが次にリセットされる日時(UNIX時間)

注意: 利用制限のしきい値は将来予告なく変更になる可能性があります。

オリジン間リソース共有(CORS)

kickflow REST APIはCORSをサポートしています。すべてのAPIはブラウザ上のJavaScriptから呼び出すことが可能です。

タイムゾーン

すべての日時のタイムゾーンはJSTです。日時のフォーマットはISO 8601に準拠します。

# 日時の例
2020-05-01T12:34:56.789+09:00

エラー

エラー発生時、下記のような形式のJSONをレスポンスボディとして返却します(メンテナンス中など、一部のサーバーエラーではこれに該当しません)。

{
  "code": "validation_failed",
  "message": "hoge must not be empty",
  "errors": {
    "hoge": [
      "must not be empty"
    ]
  }
}

JSONには下記のフィールドが含まれます。

フィールド 必須 説明
code o エラーコード
message o エラーメッセージ
errors   フィールドごとのエラーのJSONオブジェクト(バリデーションエラー発生時のみ)
doc_url   参照ドキュメントのURL(一部のエラーのみ)

Copyright © 2021 kickflow, Inc.