API

ScrewdriverのAPIとデータモデルはSwaggerを使ってドキュメント化されています。ドキュメントが古くなることを防ぐため、自動生成され、人が読みやすいインタフェースになっています。

現在のAPIはVersion 4で、全てのAPIは/v4で始まります。

APIのドキュメントは次のURLで確認できます: api.screwdriver.cd/v4/documentation

各自のScrewdriver.cdインスタンスでは、<API URL>/v4/documentationにアクセスしてください。

APIを使用する

Swagger経由で使用する

Swaggerのドキュメントは例とお試しのための編集可能なパラメータを含んでいます。/v4/documentationにアクセスし、APIを呼び出すためのTry it out!ボタンをお試しください。

Swaggerページ: Swagger page

レスポンス: Swagger response

より詳細なドキュメントは、Modelのリンクをクリックしてください。

Swaggerモデル: Swagger model

RESTクライアント経由で実行する

PostmanのようなRESTクライアントをAPIリクエストに使用します。その際、認証トークンが必要です。認証トークンを取得するためには、/v4/auth/loginからログインし、リダイレクト先の/v4/auth/tokenからトークンをコピーしてください。詳しくは認証と認可をご覧ください。

APIリクエストの際のヘッダは以下のようになります。

Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN_HERE>

リクエストの例: Postman response

ユーザまたはパイプライントークンを利用して実行する

APIを利用した簡単なスクリプトのためには、トークンを利用することを推奨します。

トークンを使用して認証する

新しく作成したトークンで認証するには、https://${API_URL}/v4/auth/token?api_token=${YOUR_TOKEN_VALUE}へGETリクエストを送ります。するとtokenのフィールドを持ったJSONオブジェクトが返ってきます。tokenフィールドの値がJSON Web Tokenになっていて、ScrewdriverのAPIへリクエストを送る際にこのJSON Web TokenをAuthorizationヘッダーに付けて使用します。このJWTは12時間の有効期限があるので、期限が切れた後には再度認証を行う必要があります。

例:パイプラインをスタートさせる

以下に、パイプランをスタートさせるためにAPIトークンを使用するやり方をPythonで記述した例があります。この例では直接APIを呼び出しています。

# トークンを使用して認証
auth_request = get('https://api.screwdriver.cd/v4/auth/token?api_token=%s' % environ['SD_KEY'])
jwt = auth_request.json()['token']

# ヘッダーをセット
headers = { 'Authorization': 'Bearer %s' % jwt }

# パイプラインのジョブを取得
jobs_request = get('https://api.screwdriver.cd/v4/pipelines/%s/jobs' % pipeline_id, headers=headers)
jobId = jobs_request.json()[0]['id']

# 最初のジョブを開始する
start_request = post('https://api.screwdriver.cd/v4/builds', headers=headers, data=dict(jobId=jobId))

詳しい情報と例についてはAPIドキュメントをご覧ください。

認証と認可

認証のために、JSON Web Tokens (JWT) を使用しています。JWTはAuthorizationヘッダを必要とします。

認可はSCMにより行われます。ScrewdriverはSCMトークンで以下を識別します。

より詳しい情報についてはGitHub OAuthのドキュメントをご覧ください。

バッジ

<your_UI_URL>/pipelines/<your_pipelineId>/badgeのURLを利用して、特定のパイプラインに対する現在のビルドステータスを表す画像を取得できます。
ジョブのステータスを表す画像は<your_UI_URL>/pipelines/<your_pipelineId>/<jobName>/badgeを利用することで取得できます。

Pipeline Status Job Status

例えば、このMarkdown形式で書かれたコードを利用することで上のようなバッジを表示できます。status-image URLはバッジの画像で、status-url はパイプラインへのリンクです。

[![Pipeline Status][status-image]][status-url] [![Job Status][job-status-image]][status-url]

[status-image]: https://cd.screwdriver.cd/pipelines/1/badge
[job-status-image]: https://cd.screwdriver.cd/pipelines/1/main/badge
[status-url]: https://cd.screwdriver.cd/pipelines/1

設計思想

ScrewdriverのAPIは次の三原則を念頭に設計されました。

  1. CLIやWebUIなど各ツールで一貫したインターフェースとするため、全てのユーザーデータへの操作をAPI経由にすべき
  2. 意図がわかりやすく、人間が読みやすくするため、リソースはREST-fulであるべきで、操作は小さく区切るべき
  3. クライアントのコード自動生成を可能にするため、APIにはバージョンがあり自己文書化されているべき

自作する

Swaggerドキュメントを作成したい場合は、次のJSONを参考にしてください: https://api.screwdriver.cd/v4/swagger.json

各自のScrewdriver.cdインスタンスでは、/v4/swagger.json にアクセスしてください。