リクエストとレスポンス

ここではすべてのメソッドに共通する、入力と出力の扱い方およびこの挙動を変更するために使用できる一般的なパラメータについて説明します。

すべての入力データはJSONでエンコードされ、応答も同様にJSONで返されます。HTTPのGETとPOSTのどちらもサポートされており、いずれのHTTPメソッドを使用した場合でも同じ応答が返されます。個々のAPIメソッドのJSONの入出力詳細についてはそれぞれのページをご参照ください。

すべてのAPIリクエストは https://api.cxense.com を参照し、特に記載がない限り認証が必要です。以下の実行例では cx.py を用いて認証ヘッダをセットしています。

GETリクエストのサポートには最新のバージョンを使用してください (version>140330!)。

POSTリクエスト

POSTリクエストではJSON入力データはメッセージボディとして送信します。

$ cx.py /profile/content/fetch '{"url":"http://www.example.com"}'

{
  "url": "http://www.example.com",
  "id": "0caaf24ab1a0c33440c06afe99df986365b0781f"
}

GETリクエスト

GETリクエストでは、JSON入力データはURLエンコードされてjsonパラメータとして送信します。さらに、GETリクエストはJSONPとレスポンスラッピング（後述）をサポートしています。

使用するOSに応じて、BashやWindows Shellではパラメータをダブルまたはシングルクォートで囲む必要があります。

BASH $ cx.py '/profile/content/fetch?json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D'

WINDOWS: C:\> cx.py "/profile/content/fetch?json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D"
 
{
  "url": "http://www.example.com",
  "id": "0caaf24ab1a0c33440c06afe99df986365b0781f"
}

レスポンスラッピング

wrap_response=trueのパラメータを与えることで、レスポンスがJSONオブジェクトでhttpStatusとresponseがラップされた形式で返されます。リクエストに対するHTTPステータスコードはリクエストが失敗したとしても常に200が返されますが、httpStatusフィールドは実際のステータスを表示し、responseはレスポンスオブジェクトを含みます。

BASH $ cx.py '/profile/content/fetch?wrap_response=true&json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D'
 
WINDOWS: C:\> cx.py "/profile/content/fetch?wrap_response=true&json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D"
{
  "httpStatus": 200,
  "response": {
    "url": "http://www.example.com",
    "id": "0caaf24ab1a0c33440c06afe99df986365b0781f"
  }
}

JSONPとコールバック

callbackパラメータでコールバックメソッドを指定することにより、レスポンスはJSONP形式に変わります。特に、HTTPのContent-Typeヘッダはtext/javascriptにセットされ、コンテンツはcallbackパラメータで指定されたメソッド名のJavaScriptとなり、レスポンスがそのメソッドの入力パラメータとなります。コールバックメソッドはASCII文字、数字、アンダースコアのみを含むことができます。

コールバックメソッドを指定することによりwrap_responseもデフォルトでtrueに設定されますが、レスポンスラッピングは明示的にoffにすることができます。

BASH $ cx.py '/profile/content/fetch?callback=callback_method&json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D'
 
WINDOWS: C:\> cx.py "/profile/content/fetch?callback=callback_method&json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D"
 
callback_method({"httpStatus":200,"response":{"url":"http://www.example.com","id":"0caaf24ab1a0c33440c06afe99df986365b0781f"}})

BASH $ cx.py '/profile/content/fetch?callback=callback_method&wrap_response=false&json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D'

WINDOWS C:\> cx.py "/profile/content/fetch?callback=callback_method&wrap_response=false&json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D"
 
callback_method({"url":"http://www.example.com","id":"0caaf24ab1a0c33440c06afe99df986365b0781f"})

レスポンスラッピングとコールバックは /traffic/data, /dmp/traffic/data API では使用できません。

バッチリクエスト

ほとんどのAPIでは複数のリクエストオブジェクトをまとめて一回のHTTPリクエストで送信することができます。これはリクエストオブジェクトをarrayとして指定することで可能です。ただしこれは複数のオブジェクトを同一のAPIに対してリクエストする場合にのみ可能です。APIが成功した場合、指定したリクエストオブジェクトと同じ数・順でレスポンスオブジェクトのarrayが返されます。

一つ以上のリクエストオブジェクトが失敗した場合にはそのオブジェクトに対するエラー結果が返されます。HTTPのステータスコードは各リクエストオブジェクトの結果中の最大値となります。

リクエスト全体が失敗した場合、応答は一つのエラーオブジェクトのみで、エラーの詳細が記載されます。これは無効なJSONオブジェクトが指定された場合や、リクエストがタイムアウトした場合、リクエストしたオブジェクト数が多すぎた場合などに発生することがあります。タイムアウトのためにバッチ全体がエラーとなる状況を避けるため、あまり多くのオブジェクトを一度にリクエストしないようにおすすめします。一度のバッチリクエストで指定できるオブジェクトの最大数は100です。

$ cx.py /profile/content/fetch '[{"url":"http://www.example.com"},{"url":"http://www.example.com/foo"},{"url":"invalid"}]'
[
  {
    "url": "http://www.example.com", 
    "id": "0caaf24ab1a0c33440c06afe99df986365b0781f", 
  }, 
  {
    "url": "http://www.example.com/foo", 
    "id": "4d5f046cfef9abccc5f77e403352712a7fd88536", 
  },
  {
    "error": "Invalid request: Invalid URL"
  }
]