APIの概要

CS-CartのAPI機能はバージョン4以降から利用できるようになりました。

CS-Cart API概要

  • RESTfulである

  • 管理者のメールアドレスと自動生成されるAPIキーを利用した HTTP Basic認証 を利用します。

  • APIはユーザーグループで定義された権限に依存しています。ユーザーグループの割り当てはオブジェクトに直接定義されています。

  • RESTを使用するために HTTP1.1 を使用しています。

以下の4つのメソッドによってデータの表示やオブジェクトの修正が可能です。

  • GET —オブジェクトデータの取得

  • PUT オブジェクトデータの更新

  • POST —オブジェクトの新規作成

  • DELETE —オブジェクト削除

データの受け渡しは、JSONフォーマットで行います。

お役立ちツール

cURLは簡単にHTTPリクエストを送信することができるクラスプラットフォームのコマンドラインアプリケーションです。UNIXベースのシステムでは、curlコマンドはデフォルトで利用可能です。

TIPS

このガイドの全ての例はcURLコマンドとして書かれています。

REST Console

REST Consoleは人気のあるGoogle Chromeブラウザ用の拡張機能です。 (同様の拡張機能は他の一般的なWebブラウザにも存在します)

＜画像＞

APIアクセスのアクティベーション

APIアクセスはユーザーごとに有効／無効の切り替えが可能です。

APIアクセスを有効にするには：

  1. CS-Cartの管理画面にログイン

  2. お客様→管理者 へ進む

  3. APIアクセスを有効にするアカウントの詳細を開く

  4. APIアクセスのタブに切り替え、APIの利用を許可にチェックを入れる

  5. 保存 をクリック

APIキーが自動的に生成され、このユーザーのEメールとAPIキーを使ってCS-CartのAPIにアクセスが可能となります。

URLs

APIのリクエストは特定のURLに通常のHTTPリクエストとして送信します。

CS-CartのAPIのURLは次のようになります：

  • http://example.com/api/:object — 全てのオブジェクトを参照

  • http://example.com/api/:object/:id — 個々のオブジェクトを参照

  • http://example.com/api/:object/:id/:nested_object: — オブジェクトの入れ子になった全てのオブジェクトを参照

  • http://example.com/api/:object/:id/:nested_object/:id —オブジェクトの入れ子になった個々のオブジェクトを参照

例えば、http://example.com/api/product/1/features でID 1の商品のデータを参照できます。

注意

CS-Cartがインストールされたサーバーでmod_rewritが無効になっている場合は、これらの例と異なるURLを使用しなければなりません：

認証

それぞれのリクエストは、ユーザーのメールアドレスとAPIキーを使って認証されなければなりません。

APIリクエストに認証データを送信するには以下の3つの方法があります：

--userパラメーター経由（全ての例はこの例で書かれています）

curl --user [email protected]:APIkey -X GET 'http://example.com/api/users/'

URL内でインラインで渡す：

curl --basic -X GET 'http://admin%40example.com:[email protected]/api/users/'

ヒント

メールアドレスの@は %40 に変換して下さい。

リクエストヘッダー

curl --header 'Authorization: Basic <base64-encoded email:APIkey pair>=' -X GET 'http://example.com/api/users/'

HINT

メールアドレスとAPIキーはbase64にエンコードする必要があります。

メールアドレスとAPIキーをbase64にエンコードするPHPのサンプルコード

<?php
$token = base64_encode("email:APIkey");
$authHeaderString = 'Authorization: Basic ' . $token;

GET : データの参照

オブジェクトデータを取得するにはGET\HTTPリクエストをオブジェクトを参照するURLに送信します。

リクエストの例

ID1の商品についてのデータを取得する：

curl --user [email protected]:APIkey -X GET 'http://example.com/api/products/1'

フィルタリング

フィルタリングを行うために追加のURLパラメーターを送信することができます。 例えば、送料無料でない商品をすべて取得する：

curl --user [email protected]:APIkey -X GET 'http://example.com/api/products?free_shipping=N'

フィルタリングの条件を組み合わせることが可能です。 company_idが１の出品者の商品かつ、ダウンロード可能な商品をすべて取得します：

curl --user [email protected]:APIkey -X GET 'http://example.com/api/products?is_edp=Y&company_id=1'

戻り値

条件に一致したオブジェクト(例：商品のキー )のJSON配列と検索クエリ(検索キー)またはエラーが返ってきます。

一致するオブジェクトの値はオブジェクトIDをキーとした配列として返ってきます。

サポートされているオブジェクト用のフィールドの完全なリストは、APIのオブジェクトを参照してください。

PUT : データの更新

オブジェクトデータを更新するには、オブジェクトに対応するURLにPUT HTTPを送信します。

PUTは、特定のオブジェクトIDを参照したURLに対してのみ使用できます(全ての商品を一度に更新することはできません)。

送信されるデータはオブジェクトフィールド用のキーや値のJSON配列である必要があります。 ( {'fieldName1: value1, fieldName2: value2} )

サポートされているオブジェクト用のフィールドの完全なリストはAPIのオブジェクトを参照してください。

重要

Content-Type のヘッダーは必ず application/json をセットして下さい。宣言が無い場合はデフォルトの text/plain が宣言され、リクエストは失敗します。

リクエスト例： ID1の商品の名前を更新する：

curl --user [email protected]:APIkey --header 'Content-Type: application/json' -d '{"product": "New Product Name"}' -X PUT 'http://example.com/api/products/1'

戻り値

更新されたオブジェクトのID（例： {"product_id":"1"} ）またはエラーが返ってきます。

POST : オブジェクトの作成

オブジェクトを作成するには、オブジェクトの種類に対応したURLにPOST HTTPリクエストを送信します。

すべてのオブジェクトタイプを参照するURLのみ使用されます（IDは使用できません）。

送信されるデータはオブジェクトフィールド用のキーと値が指定されたJSON配列である必要があります。( { fieldName1: value1, fieldName2: value2} )

一部のフィールドはオブジェクトの作成に必須となるものがあります。詳細はAPIのオブジェクトの各ページを参照してください。

重要

Content-Type のヘッダーは必ず application/json をセットして下さい。宣言が無い場合はデフォルトの text/plain が宣言され、リクエストは失敗します。

リクエスト例

「My Awesome Product」という名前の新しい商品を作成します：

curl --user [email protected]:APIkey --header 'Content-Type: application/json' -d '{"product": "My Awesome Product"}' -X POST 'http://example.com/api/products'

戻り値

作成されたオブジェクトのID。例： {"product_id":"1"} またはエラーが返ってきます。

DELETE : オブジェクトの削除

オブジェクトを削除するには、オブジェクトに対応するURLにDELETE HTTP リクエストを送信します。

特定のオブジェクトIDを参照するURLのみ使用が可能です。（一度に全ての商品を削除することは出来ません）

リクエスト例

id 12の持つ商品を削除する：

curl --user [email protected]:APIkey -X DELETE 'http://example.com/api/products/12'

戻り値

操作が成功してもレスポンスはありません。

次へAPIレスポンスエラー

最終更新