ドキュメントAPIリファレンスCS-Cart.jp
APIリファレンス

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ブラウザにも存在します)

726

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が１の出品者の商品かつ、ダウンロード可能な商品をすべて取得します：

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'

戻り値

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