CCW APIの概要

CCWのREST APIを使用すると、顧客とパートナーは新しいアプリケーションを構築し、新しい方法でCCWと統合して、臨時従業員の管理に関する機能を改善できます。CCWのAPIはHTTPベースのRESTful APIで、認証にOAuth 2.0、トランスポート層のセキュリティにTLS 1.2を使用します。このドキュメントでは、CCWのAPIにアクセスして必要なデータを取得するリクエストを行う方法について説明します。

認証

CCW REST APIにアクセスする必要のあるお客様は、次の操作を行うことができます apiコンシューマーアプリを登録する CCW APIへのリクエストを認証するために、スコープとユーザー/役割のアクセス権という2つの追加のセキュリティーレイヤーと組み合わせて使用するOAuth 2.0クライアント認証情報を受け取ります。

アクセストークン

CCW APIにアクセスする最初のステップは、次の例に示すように、OAuth認証情報とスコープを使用して呼び出しを行うことで、アクセストークンを要求することです。

curl -XPOST -H "Content-type: application/json" -d '{"client_id": "<<clientID>>", "client_secret": "<<secret>>", 
"scope":"ccw.candidate", "grant_type":"client_credential"}' 'Auth_Url'

「Auth_Url」については、環境に応じて次を使用します。

• サンドボックス： https://sso-stg1.coupahostを参照してください。 com/as/token.oauth2
• 本番： https://sso-prd1.coupahostを参照してください。 com/as/token.oauth2

承認サーバーは、以下を含むJSONペイロードを返します。

APIエンドポイント

受信したアクセストークンをCCW APIエンドポイントへのコールに含めます。申請が検証された(またはエラーを返す – エラーコード ）をクリックします。

終点の形式： https://<instance>/api/<resource path>

例:

• 候補者確認： https://{hostname}/API/candidates/{id}/confirm
• 候補者検索： https://{hostname}/API/候補/検索
• 臨時従業員(CW)検索： https://{hostname}/API/contingent_workers

リクエストヘッダー

次のHTTPリクエストヘッダーが必要です。

エラー応答

サンプルのエラー応答

{
 "error_code": "string",
 "error_summary": "string", 
 "error_causes": [
  {
   "error_sub_code": "string",
   "error_sub_code_desc": "string"
  }
 ]
}

エラーコード

それぞれの特定のCCW APIのエラーコードセクションを参照してください。

• 候補者検索API - エラーコード
• 候補者確認API - エラーコード
• CW検索API - エラーコード

レート制限

CCW REST APIには明示的なレート制限はありませんが、タイムリーな応答を得るためにAPIリクエストのスロットルを推奨します。近日中に、個別のAPIエンドポイントが推奨レート制限で更新されます。

ベストプラクティス

以下は、REST APIを使用してCCW上にアプリケーションを構築する際に最良の結果を得るためのヒントです。

1. スキーマ検証を回避： CCW APIは常に進化しており、新しいオプションプロパティがAPIに追加されています。拡張性を目的として、アプリケーションはスキーマ検証を実行しないでください。スキーマ検証は、不要な可能性のある新しいプロパティがAPIによって送信されたときにエラーをトリガーする可能性があります。
2. HTTPステータスコードを使用： コンシューマーアプリケーションは、診断およびロギングのみを目的とする応答本文の内容ではなく、APIエラーの処理にHTTPステータスコードを使用する必要があります。
3. API応答のプロパティの順序に依存しないようにしてください。 CCW APIはJSONコンテンツのみをサポートします。新しいプロパティの導入により、API応答のプロパティの順序が変更される場合があります。