CCW APIの概要

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

認証

CCW REST APIへのアクセスを希望されるお客様は、APIコンシューマーアプリを登録し、OAuth 2.0クライアント認証情報を受け取り、スコープとユーザー/役割アクセス権の2つの追加のセキュリティレイヤーと組み合わせて使用して、CCW APIへのリクエストを認証できます。


認証要件	Description
OAuth 2.0認証情報	クライアントIDとクライアントシークレットを含む
スコープ	リクエストされているCCW内の特定のモジュール/機能を指すエンドポイント
ユーザー/役割アクセス権	CCWアプリケーション内で割り当てられます。 APIによって認証されると(下記参照)、別のセキュリティレイヤーが要求されている特定の機能へのアクセスを決定します

アクセストークン

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://identity-stg0-na10001.io.coupahost.com/realms/ccw-na-stg/protocol/openid-connect/token （北米）
- https://identity-stg0-eu10009.io.coupahost.com/realms/ccw-eu-stg/protocol/openid-connect/token （ヨーロッパ）
本番:
- https://identity-prd0-na10001.io.coupahost.com/realms/ccw-na-prd/protocol/openid-connect/token （北米）
- https://identity-prd0-eu10009.io.coupahost.com/realms/ccw-eu-prd/protocol/openid-connect/token （ヨーロッパ）

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


プロパティ	価値
token_type	「Bearer」で固定
access_token	APIリクエストを行うときに承認ヘッダーに含まれる文字列
expires_in	トークンの有効期限が切れるまでの秒数(通常は3600秒または1時間)

APIエンドポイント

CCW APIエンドポイントへの呼び出しで受信したアクセストークンを含みます。

エンドポイント形式： https ://<instance>/api/<resource path>

例:

候補者確認: https://{hostname}/API/candidates/{id}/confirm
候補者検索: https://{hostname}/API/candidates/search
有期契約作業員 (CW) 検索: https://{hostname}/API/contingent_workers

申請ヘッダー

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


ヘッダー	Description
認証	API呼び出しのアクセスをリクエストするために使用されます。認証スキームにBearerトークンを含みます。Bearer: <Token>
Content-Type	すべてのリクエストでapplication/jsonに設定します。 JSONは現在サポートされている唯一の交換フォーマットです
X-Correlation-id	APIリクエストの追跡と監査を可能にするために生成される最大36文字の識別子

エラーレスポンスのサンプル

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

レート制限

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

ベストプラクティス

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

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

Coupa Documentation