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コマンドはデフォルトで利用可能です。

📘

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

REST Console

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

REST ConsoleREST Console

REST Console

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

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

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

  1. CS-Cartの管理画面にログイン
  2. お客様→管理者 へ進む
    3 .APIアクセスを有効にするアカウントの詳細を開く
  3. APIアクセスのタブに切り替え、APIの利用を許可にチェックを入れる
  4. 保存 をクリック

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/'

📘

ヒント

メールアドレスと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が1の出品者の商品かつ、ダウンロード可能な商品をすべて取得します:

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'

戻り値

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