REST API

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

Table of contents

  1. エンドポイント
  2. 各APIの詳細
  3. 認証
    1. アクセストークンの種類
    2. Personal Access Tokenによる認証
    3. Service Account Tokenによる認証
    4. 認証失敗時
  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の定義ファイルはこちらからダウンロードできます。

認証

アクセストークンの種類

kickflowではアクセストークンによる認証を行います。 アクセストークンにはユーザー個人に紐づくPersonal Access Tokenと、テナント全体にアクセス可能なService Account Tokenの二種類のアクセストークンがあります。

Personal Access Tokenはトークンを発行したユーザーの操作を自動化するのに使用します。一方、Service Account Tokenはテナント内の任意のユーザーになりすまして自動的に何らかの操作を実行するのに使用します。

Service Account Tokenは万が一漏洩した際に影響が大きいため、どうしても必要でない限りはPersonal Access Tokenの使用を検討してください。

Personal Access Tokenによる認証

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

Authorization: Bearer <アクセストークン>

Service Account Tokenによる認証

Personal Access Tokenと同様、AuthorizationヘッダにService Account Tokenを設定します。 さらに、なりすましたいユーザーのIDをX-Caller-Idヘッダに設定します。

Authorization: Bearer <アクセストークン>
X-Caller-Id: <ユーザーID>

認証失敗時

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

Role-based Access Control (RBAC)

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

ページネーション

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

  • pageは何ページ目かを表します。1が最初のページです（0ではないことに注意してください）。設定しない場合、page=1とみなします。
  • perPageは1ページあたり何件のレコードを返すかを表します。デフォルト値は25で、最大100まで設定可能です。

レスポンスには RFC-8288 によるLinkヘッダーが付加されます。 さらに、現在のページ、1ページあたりの件数、合計件数もヘッダーに含まれます。

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"
Page: 1
Per-Page: 100
Total: 4950

ソート

一部の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.