用語と構文

CSOと別のデータベース間でデータを交換するためのすべてのAPI呼び出しは、 https :// プロトコルを使用して行われます。 交換対象となるデータ(リソース)は、データタイプやそれを保持するオブジェクト(マーケット、イベント、ファクトシートなど)の名前に続けて、CSO内の特定オブジェクトまたはデータセットのIDを指定する形式で以下のように記述されます。

https://{CSOサイト名}/api/{リソース名}/{リソースID}

顧客CSOサイトの名前は {company_name}.cso.coupahost.comになります なお、APIコールでは、リソースの名前ではなくIDを使用して特定のリソースを指定する点に注意してください。

APIコールはJSON (JavaScript Object Notation)形式で記述されます。 SON は軽量でテキストベースのオープンスタンダードなフォーマットであり、システム間のデータ転送によく使用されます。 もともとはJavaScriptアプリケーション向けに開発されたものですが、特定のプログラミング言語に依存せず、多くの言語で利用可能なパーサーやツールが用意されています。

認証

CSOサーバーとサードパーティサーバー間のデータ交換の認証は、一意のAPIキーを介して行われます。 このAPIキーはCoupaによって生成され、 CSOに保存され、APIユーザーに紐づけられます。 APIキーはすべてのAPIリクエストのヘッダーに含める必要があり、ヘッダー名はX-CSO-API-KEYです。また、Acceptヘッダーには'application/json'を設定する必要があります。

リクエスト

上述の構文に従うと、イベントIDが12312224の中にあるファクトシートID 342333のフィールドを取得するリクエストは、以下のようになります。

https://{CSOサイト名}/api/events/12312224/fact-sheets/342333/fields

特定のデータセットを取得するには複数のリクエストが必要になる場合があります。たとえば、まずイベントの一覧を取得してから対象イベントのIDを取得し、そのイベント内のファクトシートを取得して、目的のファクトシートのIDを得るという流れです。 外部システム側でこれらのIDを保存しておけば、フィールドやファクト行に一括でアクセスすることが可能になります。

ファクトフィールドのいずれかにタイムスタンプ、更新シーケンス番号、あるいはその他の種類のフラグを格納することで、前回の更新以降の新しいデータのみを取得するリクエストを送信でき、パフォーマンスの問題を回避できます。

リクエストメソッド

GET (データの読み取り)

• limit:返すオブジェクトの数を指定

• offset:データセット内の開始位置を指定し、limitで指定した件数をそこから返す

例 ： https ://{name_of_cso_site}/api/markets? offset = 10 & limit = 5 は、CSOで見つかった市場のリストの位置10から始まる次の5つの市場を返します。 マーケットが15件未満の場合は、返される件数はそれより少なくなります。

PUT （データ更新）

PUTリクエストは、サードパーティシステムからCSOへデータを送信し、既存のデータを更新します。

例 ： api/markets/{id} は指定されたIDで市場を更新しますが、api/marketsは要求本文で指定されたすべての市場（ ID ： sによって）を更新します。

更新は寛容に処理されます。つまり、1つのリソースの更新に失敗しても、他のリソースは成功する場合があります。

POST (データの作成または挿入)

POSTリクエストはCSO内の指定されたリソースにデータを新規作成または挿入します。 成功した場合、新しいデータやリソースのIDが返されます。

削除（データ削除）

データの削除は一部のリソースタイプでのみサポートされています。 単一のリソースに対して、または一括操作で削除可能です。 削除されたデータは完全かつ永続的に消去され、CSO内で復元できません。 したがって、DELETEメソッドは十分に注意し、慎重に使用してください。

レスポンス

CSO APIからのレスポンスには、ステータスコードとJSON形式の本文が含まれます。

コード200は一般的な成功のインジケーターです。 POSTリクエストの場合、データの作成に成功したことを示すコード201が返されます。

エラーが発生した場合は、4xx系のエラーコードが返されます。 これは、サポートされていない操作や許可されていないリクエストによって引き起こされるのが一般的です。 不明な理由で失敗した場合はコード500が返されます。 このような失敗に対しては、再送しても失敗するため、再試行はしないでください。 レスポンスコードの詳細については、こちらを参照してください。

一部のパラメータは、名称の衝突などを回避するために編集が必要な場合がありますが、GETリクエストのレスポンスは、大部分のケースでPUTまたはPOSTリクエストの本文にそのまま利用できます。 特定のデータ型におけるリクエスト形式が不明な場合は、APIを使ってGETレスポンスを取得することで、正しい形式を確認することが可能です。

文書

OpenAPIスキーマは、すべてのCSOサイトにおいてhttps://{CSOサイト名}/openapi.htmで確認可能です。 文書には、アクセス可能なオブジェクト(market、user、fact sheetなど)およびデータタイプ、それぞれに対して許可されているリクエストが記載されています。 各リクエストをクリックすると、関連するJSON形式のスキーマが表示されます。

参考用の例

マーケットを取得する

https ://{name_of_cso_site}/api/marketsに移動

レスポンスコード: 200

レスポンス本文:

{" total ": 70 ," markets ":[{" id ":" 9219593111199654844 "," name ":" Market A "," description ":" A descriptive text ." ｝ ， ｛" id "：" 9219593111199654844 "，" name "：" Market B "｝， … 68以上の市場があります。 ] }

マーケットBの説明が省略されています。JSONを使用する場合、空の値やnullの値は送信しないようにしてください。

マーケットを作成する

https ://{name_of_cso_site}/api/marketsに投稿

リクエスト本文:

{" name ":" First Market "," description ":"市場を説明するオプションのテキスト。" }

レスポンスコード: 201

レスポンス本文:

{" result ":[{" type ":" api.post.added "," description ":" 1個のオブジェクトが作成されました。" }]," ADDED ": 1 ," MARKETS ":[{" id ":" 9219593535573352536 "}]}

レスポンス本文には、CSOによって新しく作成されたマーケットのIDが含まれます。

マーケットを更新する

https ://{name_of_cso_site}/api/markets/{market_id}に置く

リクエスト本文:

{" name ":"名前が変更された最初のマーケット"}

レスポンスコード: 200

レスポンス本文:

{" result ":[{" type ":" api.put.updated "," description ":" 1個のオブジェクトが更新されました。" }], "updated ": 1}

属性「updated」には、PUTリクエストによって更新されたオブジェクトの数が含まれます。