eBay REST APIの基本

eBay REST APIの基本 (eBay REST Essentials)

概要

このガイドでは、高レベルのREST呼び出しとレスポンスの仕組みについて説明します。また、eBay APIを使用してアプリケーションを作成する際に必要となる、OAuthトークンの生成方法やエラーメッセージの解析方法などの情報も提供します。

RESTとは?

RESTは Representational State Transfer の略です。実際には、ユーザーまたはプログラムが、HTTPリクエストとレスポンスなどの標準的なWebコマンドとプロトコルを使用して、リモートで実行されているサービスと通信することを意味します。

サービスに対してHTTPリクエストにラップされたAPIコマンドを送信すると、サービスは成功または失敗のインジケーターと結果データを含むHTTPレスポンスを返します。これは、REST API自体がステートレスであることを意味します。状態はクライアント側またはサービス側のいずれかで維持されますが、API内では維持されません。そのため、正式名称はRepresentational State Transfer（表現状態転送）と呼ばれます。

REST APIは、クライアントからサーバーへ、あるいはその逆に状態を転送します。

RESTを使用するメリット

RESTの主なメリットは、HTTPが広く普及していることです。また、HTTPリクエストとレスポンスの送受信は、それほど多くの帯域幅を消費しません。さらに、RESTで使用される構文とプロトコル（JSONとURIアドレス指定プロトコル）は広く知られており、Webの利用方法として定着しています。基盤となるシステムは既に構築・導入されており、誰でも利用可能です。そのため、ユーザーと開発者がアプリケーションを稼働させるために必要な作業量は最小限に抑えられます。

理論上、すべてのRESTful APIは、習得しやすい共通のインターフェース形式を備えています。RESTアーキテクチャは、クライアントとサービス間のインタラクションを強化するために、処理対象となる操作の数を限定することを重視しています。具体的には、完全な「CRUD」機能を提供する4つの一般的なHTTPメソッド（Create、Retrieve、Update、Delete）があります。主なHTTPメソッド（GET、POST、PUT、およびDELETE）はそれぞれRESTアーキテクチャ内で特定の意味を持ち、これによりRESTでは曖昧さを回避しています。HTTPメソッドは、REST操作における動詞と考えることができます。柔軟性を確保するために、リソース には独自の一意なUniform Resource Identifier（URI）を割り当てます。リソースはREST操作における名詞であり、多くの場合、単一のエンティティまたは同様のエンティティのグループで構成されます。

このガイドでは、以下のトピックについて説明します。

呼び出しの実行 — 3つの手順でeBay APIへの呼び出しを実行する方法。
リクエストコンポーネント — RESTリクエストの構成要素と、その組み立て方。
レスポンスコンポーネント — RESTレスポンスの構成要素と、その解析および解釈の方法。
エラーメッセージの処理 — HTTPレスポンスがエラーメッセージと警告メッセージを返すためのeBayの共通形式について説明します。
API Explorerを使用してサンプル呼び出しを実行する — API Explorerは、eBay APIのすべてのメソッドのサンプル呼び出しを実行できるツールです。
バージョン管理とAPIライフサイクル — 各APIはAPIライフサイクルを経て、リリース、更新、そして最終的には廃止というさまざまな段階を経ます。
アプリケーション開発のサポート — アプリケーションの開発で問題が発生した場合に、どこでどのようにサポートを受けられるかについて。

呼び出しの実行

最初のeBay REST API呼び出しを実行するには、次の手順に従います。

手順 1: eBay開発者プログラムアカウントがない場合は、「eBay開発者プログラムに参加する」ガイドの手順に従います。アカウントをお持ちの場合は、手順2に進んでください。
手順 2: アクセストークンを取得してキーセットを作成します。
- 「eBay APIキーセットの作成」トピックの手順に従って、サンドボックスまたは本番環境のキーセットを作成します。
- 「クライアント資格情報付与フロー」トピックの手順に従って、アプリケーションのOAuthアプリケーショントークンを生成します。
手順 3: API Explorerツールを使用して、getItemConditionPolicies 呼び出しを行います。手順2で作成したアプリケーショントークンを使用します。詳細については、「API Explorerを使用してAPIを試す」を参照してください。

リクエストコンポーネント

3つの主要なリクエストコンポーネントについて、以下のサブセクションで詳しく説明します。

HTTPリクエストヘッダー
REST APIエンドポイント
リクエストペイロード

HTTPリクエストヘッダー

すべてのeBay REST APIメソッドには少なくとも1つのHTTPリクエストヘッダーが必要です。また、メソッドによっては複数のヘッダーが必要な場合があります。これらのヘッダーには、標準のHTTPヘッダーとeBayカスタムヘッダーの両方を含めることができます。すべてのeBayカスタムヘッダーは "X-EBAY-C-" で始まります。

eBayのカスタムヘッダーの中には パックヘッダー と呼ばれるものがあり、複数の名前/値のペアを含むことができます。名前/値のペアの形式は <name>=<value> で、1つのヘッダー内の複数の値はカンマで区切る必要があります。次の例は一般的な形式を示しています: X-EBAY-C-PACKED-EXAMPLE: fig=7,bar="quux",value=42

次の表は、eBayが受け入れる標準のリクエストヘッダーと、使用できるeBayカスタムヘッダーを示しています。

注: すべてのヘッダーは大文字と小文字を区別せず、RFC標準に従う必要があります。

eBay RESTリクエストのHTTPヘッダー

HTTPヘッダー	必須	説明
Authorization	必須	Authorization は、リクエストを認証するために使用されるOAuthトークンとトークンタイプを指定します。eBay RESTインターフェースに送信するリクエストごとに、このリクエストヘッダーを指定する必要があります。詳細については、「OAuthアクセストークン」を参照してください。例: Authorization: Bearer <accessToken>
Accept	条件付きで必須	Accept は、クライアントがレスポンスとして受け入れる形式を示します。このヘッダーは、eBayが要求するリクエストボディの形式を指定する Content-Type ヘッダーとペアになります。現在、ほとんどのeBay RESTインターフェイスでは、リクエストボディをJSON形式にする必要があります。詳細とその他のサポートされているヘッダーについては、Content-Type ヘッダーを参照してください。JSONはデフォルトで、レスポンスボディで返される唯一の形式です。例: Accept: application/json
Accept-Charset	オプション	Accept-Charset は、クライアントがレスポンスとして受け入れる文字セットを示します。サーバーが Accept-Charset で指定された値を使用して応答できない場合、サーバーは通常その値を無視し、エラーなしで utf-8 で応答します。例: Accept-Charset: utf-8
Accept-Encoding	オプション – 条件付きで推奨	Accept-Encoding は、クライアントがレスポンスとして受け入れる圧縮エンコーディングアルゴリズムを示します。大きなレスポンスペイロードを返す可能性があるすべてのリクエストにこのヘッダーを含めることを強くお勧めします。圧縮エンコーディングは、レスポンスペイロードのサイズを大幅に削減することでパフォーマンスを向上できます。現在サポートされている圧縮形式は gzip のみです。例: Accept-Encoding: gzip
Accept-Language	条件付きで必須	Accept-Language は、レスポンスにクライアントが優先する自然言語とロケールを示します。すべてのリクエストに推奨されますが、複数のロケールをサポートするマーケットプレイスの特定のロケールを指定する場合は、このヘッダーが必須です。例: * ベルギーマーケットプレイスのフランス語ロケールを指定する場合は fr-BE を使用します。 * カナダマーケットプレイスのフランス語ロケールを指定する場合は fr-CA を使用します。さまざまなeBayマーケットプレイスでサポートされている言語値とロケールについては、「マーケットプレイスID値」を参照してください。例: Accept-Language: fr-CA
Content-Type	条件付きで必須	Content-Type は、クライアントから提供されたリクエストボディの形式を示します。このヘッダーは、クライアントがレスポンスとして受け入れる形式を示す Accept ヘッダーとペアになります。現在、すべてのAcceptヘッダーはJSON形式です。詳細は Accept ヘッダーを参照してください。このヘッダーは通常、すべての POST および PUT 操作に必須です。リクエストで省略された場合、このヘッダーはデフォルトで application/json になります。サポートされる値は次のとおりです: Content-Type: application/json Content-Type: multipart/form-data Content-Type: application/octet-stream
Content-Language	条件付きで必須	このヘッダーは、ユーザー定義のテキストをサポートするリクエストペイロードフィールドで使用される自然言語を設定します。このヘッダーでサポートされる値には、英語の場合は en-US、ドイツ語の場合は de-DE などがあります。このヘッダーはすべてのリクエストで推奨されますが、複数のロケールをサポートするマーケットプレイスの特定のロケールを指定する場合には必ず指定してください。例: * ベルギーマーケットプレイスのフランス語ロケールを指定する場合は fr-BE を使用します。 * カナダマーケットプレイスのフランス語ロケールを指定する場合は fr-CA を使用します。さまざまなeBayマーケットプレイスでサポートされている言語の値とロケールについては、「マーケットプレイスID値」を参照してください。

この一般的なHTTPヘッダーセットに加えて、一部のメソッドまたはAPIでは追加のヘッダーが使用されます。インターフェイスへのリクエストを行うために必要となる可能性のある追加のヘッダーの詳細については、各メソッドのドキュメントを確認してください。

マーケットプレイスID値

次の表は、サポートされているマーケットプレイスID、それらに関連付けられている国/地域、マーケットプレイスのURL、および各マーケットプレイスでサポートされているロケールを示しています。

マーケットプレイスID	国/地域	マーケットプレイスサイト	ロケールサポート
EBAY_US	米国	www.ebay.com (米国の自動車またはP&Aカテゴリのアイテムについては、EBAY_MOTORS_US を使用してください。)	en-US
EBAY_AT	オーストリア	www.ebay.at	de-AT
EBAY_AU	オーストラリア	www.ebay.com.au	en-AU
EBAY_BE	ベルギー	www.benl.ebay.be (オランダ語) www.befr.ebay.be (フランス語)	nl-BE, fr-BE
EBAY_CA	カナダ	www.ebay.ca (英語) www.cafr.ebay.ca (フランス語)	en-CA, fr-CA
EBAY_CH	スイス	www.ebay.ch	de-CH
EBAY_DE	ドイツ	www.ebay.de	de-DE
EBAY_ES	スペイン	www.ebay.es	es-ES
EBAY_FR	フランス	www.ebay.fr	fr-FR
EBAY_GB	イギリス	www.ebay.co.uk	en-GB
EBAY_HK	香港	www.ebay.com.hk	zh-HK
EBAY_IE	アイルランド	www.ebay.ie	en-IE
EBAY_IT	イタリア	www.ebay.it	it-IT
EBAY_MY	マレーシア	www.ebay.com.my	en-US
EBAY_NL	オランダ	www.ebay.nl	nl-NL
EBAY_PH	フィリピン	www.ebay.ph	en-PH
EBAY_PL	ポーランド	www.ebay.pl	pl-PL
EBAY_SG	シンガポール	www.ebay.com.sg	en_US
EBAY_TW	台湾	www.ebay.com.tw	zh-TW
EBAY_MOTORS_US	米国	www.ebay.com/motors (EBAY_USサイトの親カテゴリ「自動車部品と車両」に解決されます。)	en-US

REST APIエンドポイント

REST操作 を指定してRESTfulリクエストを作成します。これは、HTTPメソッド と、関連付けられた Uniform Resource Identifier (URI) で構成されます。

HTTPメソッド

使用可能なすべてのHTTPメソッドは、W3CのRFC 9110、セクション9.3で定義されています。次の表に、eBay REST APIがサポートするHTTPメソッドを示します。

HTTPメソッド	説明
POST	POSTメソッドは、リクエストに含まれるエンティティを、URIで識別されるWebリソースの新しい従属エンティティとしてサーバーが受け入れることを要求します。例として、POSTされたデータは、既存のリソースへの注釈、掲示板・ニュースグループ・メーリングリスト・コメントスレッドへのメッセージ、Webフォームからデータ処理プロセスへの送信データ、またはデータベースに追加するアイテムなどが考えられます。
PUT	PUTメソッドは、リクエストのボディで渡されるエンティティを指定されたURIの下に格納するように要求します。URIが既存のリソースを参照している場合、そのリソースは変更されます。URIが既存のリソースを指していない場合、サーバーはそのURIを使用してリソースを作成できます。
GET	GETメソッドは、指定されたリソースの表現を要求します。たとえば、アドレスリソースを取得するメソッドは、特定のアドレスリソース（またはアドレスリソースのセット）の表現を取得します。GETを使用するリクエストはデータを取得するだけであり、他の作用や副作用があってはなりません。
DELETE	DELETEメソッドは、指定されたリソースを削除します。

REST操作のURI

REST操作のURI部分は、操作が実行される リソース を指します。例として、以下は、一意の識別子 orderId に基づいて注文の内容を取得するために Fulfillment API の GET 操作で使用されるURIです:

https://api.ebay.com/sell/fulfillment/v1/order/{orderId}?fieldGroups=string

このURIは、いくつかの個別の情報を組み合わせることで作成されます:

eBay REST URIのコンポーネント

URIプロパティ	説明
https://api.ebay.com	APIが存在するドメイン（APIの場所）。eBayでは、本番環境やサンドボックス環境など、さまざまなAPI 環境がサポートされています。サポートされているeBay API環境のアドレス指定方法の詳細については、「eBay API環境」を参照してください。
/sell	APIコンテキスト（購入、販売、コマース、開発者など）。
/fulfillment	API名。
/v1	APIのメジャーバージョン。
/order	操作の対象となるリソース。一部のメソッドはリソースの特定のインスタンスに対して操作を行い、他のメソッドはリソースの複数のインスタンスに対して操作/取得を行う場合があります。URIが特定のリソースを指定しない限り、操作はリソースコレクション（同様のリソースのセット）を指定します。
/{orderId}	パスパラメータと呼ばれるこれらは、リソースの特定のインスタンスを指定する場合に最もよく使用されます。
?fieldGroups=文字列	一部の操作は1つ以上のクエリパラメータをサポートしており、これにより操作の対象をより細かく制御できます。

URIパラメータ

上記のように、REST操作ではURIに パラメータ を含めることができます。具体的には、パスパラメータとクエリパラメータの両方を持つことができます。

パスパラメータ は、操作の「パス」セグメントの一部となる変数です。これらの変数は操作のパスの一部となるため、常に必須です。
複数のクエリパラメータはアンパサンド ("&") で区切ります。クエリパラメータ は、RESTメソッドの設計に応じて、オプション、条件付きで必須、または必須になります。

クエリパラメータ値のURLエンコード

一部のパスパラメータでは値を含める必要はありませんが、値を含める必要がある場合もあります。sort クエリパラメータは通常、結果を並べ替えるフィールドを指定する必要があります。パスパラメータに値を追加する必要がある場合は、必ず追加した値を URLエンコード する必要があります。URLエンコードは「パーセントエンコーディング」と呼ばれることもあります。

次の例について考えてみましょう:
/buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}

上記のURIには、3つのクエリパラメータ q 、 category_ids 、および aspect_filter が含まれています。最初の2つのパラメータは単純ですが、3つ目 (aspect_filter) は少し複雑で、2つの異なる値を指定しています。

これらのクエリパラメータに指定する各値は、次の表に示すようにURLエンコードする必要があります。

URLエンコードされたクエリパラメータ値

パスパラメータ値	URLエンコード値
shirt	shirt
15724	15724
categoryId:15724,Color:{Red}	categoryId%3A15724%2CColor%3A%7BRed%7D

ご覧のとおり、最初の2つの値のURLエンコードは文字列値を変更しません。ただし、3番目の値には、エンコード時に特殊なコードでレンダリングされる文字が含まれています。

この例では、操作への完全なURLエンコードされたURIは次のようになります:
/buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId%3A15724%2CColor%3A%7BRed%7D

URLエンコードの詳細については、Wikipediaの「パーセントエンコーディング」などを参照してください。

eBay APIサンドボックス環境

ほとんどのeBay REST APIは、サンドボックス環境をサポートしています。この環境では、アプリケーションを本番環境に移行する前に、さまざまなAPIを使用してテストできます。

REST API内の各メソッドのリファレンスドキュメントには、本番用URIとサンドボックス用URIが記載されています。一般的に、ベースURIパスは非常に似ています。ベース本番URIが https://api.ebay.com の場合、サンドボックスURIは https://api.sandbox.ebay.com になります。サンドボックスを使用したテスト方法の詳細については、「テストサンドボックスユーザーの作成」を参照してください。

リクエストペイロード

リクエストボディ（多くの場合「ペイロード」と呼ばれます）は、リソースを作成または更新するたびにリクエストと共に提供されます。eBay REST APIでは、ほとんどのリクエストペイロードとすべてのレスポンスペイロードはJSON形式です。APIリファレンスドキュメントでは、各メソッドのボディでサポートされるフィールドについて説明しています。

次のサンプルリクエストペイロードは、商品割引を作成するメソッドである POST https://api.ebay.com/sell/marketing/v1/item_promotion リクエスト用です:

{
  "marketplaceId": "EBAY_US",
  "inventoryCriterion": {
    "listingIds": [
      "142250172493",
      "132073034350"
    ],
    "inventoryCriterionType": "INVENTORY_BY_VALUE"
  },
  "endDate": "2027-03-01T20:00:00.000Z",
  "discountRules": [
    {
      "discountSpecification": {
        "numberOfDiscountedItems": 1,
        "forEachQuantity": 1
      },
      "ruleOrder": 0,
      "discountBenefit": {
        "percentageOffItem": "5"
      }
    }
  ],
  "name": "1点購入で2点目が5%オフ - パート2",
  "description": "1点購入で2点目が5%オフ - パート2",
  "startDate": "2025-02-11T19:58:18.918Z",
  "promotionStatus": "DRAFT"
}

レスポンスの構成要素

レスポンスの主要構成要素は以下のとおりです。それぞれ、後続のサブセクションで説明します。

HTTPステータスコード
レスポンスペイロード
HTTPレスポンスヘッダー

HTTPステータスコード

eBay REST操作に対するリクエストからの各レスポンスには、リクエストのステータスを示す HTTPステータスコード が含まれています。HTTPステータスコードは、W3C RFC 2616、セクション10で定義されています。高レベルのコードは次のように定義されています。

HTTPステータスコード

高レベルのHTTPステータスコード	説明
1xx	Informational — 100番台のコードは、レスポンスにスイッチングプロトコルメッセージなどの情報データが含まれていることを示します。
2xx	Success — 200番台のコードは、リクエストが正常に受信され、理解され、受け入れられたことを示します。 200 コードは OK を示しますが、他の200番台のコードは他の種類の成功を示す場合があります。
200	OK — リクエストが成功しました。レスポンスで返される情報は、リクエストで使用されたメソッドによって異なります。
201	Created — リクエストが満たされ、新しいリソースが作成されました。新しく作成されたリソースは、返されたURIの Location ヘッダーフィールドで参照できます。
202	Accepted — リクエストは処理のために受け入れられましたが、処理はまだ完了していません。
204	No Content — サーバーはリクエストを処理しましたが、エンティティボディ（ペイロード）を返す必要はありません。
3xx	Redirection — 300番台のコードは、リクエストがリダイレクトされたことを示します。
4xx	Client Error — 400番台のコードは、何らかのクライアントエラーが発生したことを示します。発生したエラーの種類の詳細については、エラーコードを確認してください。
400	Bad Request — 構文エラーのため、サーバーがリクエストを理解できませんでした。
401	Unauthorized — リクエストにはユーザー認証が必要ですが、提供されなかったか、提供されたユーザー認証が拒否されました。
404	Not Found — サーバーはリクエストURIに一致するものを見つけることができませんでした。
5xx	Server Error — 500番台のコードは、サーバー側でエラーが発生したことを示します。詳細については、特定のエラーを参照してください。

レスポンスペイロード

リクエストペイロードと同様に、eBay REST操作の呼び出しからのすべての正常なレスポンスには、JSON形式のペイロードが含まれます（該当する場合）。以下のコード例は、GET https://api.sandbox.ebay.com/buy/v1/deals 呼び出しからのレスポンスペイロードを示しています。このペイロードには、指定されたカテゴリの現在のeBay Deals商品のリストが含まれています。

{
  "deals": [
    {
      "groupId": "v1|1*********|0",
      "title": {
        "content": "Apple iPhone 4S - 32GB - White Smartphone-14485"
      },
      "imageLink": "http://i.ebayimg.ebay.com/0*****/$_35.JPG",
      "minPrice": {
        "value": 300,
        "currency": "USD"
      },
      "maxPrice": {
        "value": 300,
        "currency": "USD"
      },
      "categoryIdentifier": "Cell Phones & Smartphones",
      "quantitySold": 12,
      "discount": true,
      "originalPrice": {
        "value": 401,
        "currency": "USD"
      },
      "quantityLimitPerBuyer": 5,
      "priceDisplayCondition": "ALWAYS_SHOW",
      "itemGroup": "/buy/v1/item_group/v1|1***********|0",
      "dealEndtime": {
        "value": "2024-11-27T14:59:00.000Z",
        "formattedValue": "2024-11-27T14:59:00.000Z"
      }
    },
    {
      "groupId": "v1|1***********|0",
      "title": {
        "content": "Packing and Shipping boxes - 19273-1445985364525"
      },
      "...": ""
    }
  ]
}

HTTPレスポンスヘッダー

eBay REST操作に対する各呼び出しからのレスポンスには、一連の HTTPヘッダー が含まれます。各操作によって返されるヘッダーは特定の操作に固有ですが、ほとんどの操作では次の表に示すHTTPヘッダーが返されます。

注: すべてのヘッダーは大文字と小文字を区別せず、RFC標準に従う必要があります。

一般的なHTTPレスポンスヘッダー

HTTPレスポンスヘッダー	説明
Content-type	レスポンスの文字セットやMIMEタイプを記述します。これは、それぞれ Accept-Charset および Accept-Encoding リクエストヘッダーで指定された値と同じである必要があります。サーバーがこれらのリクエストヘッダーのいずれかで指定された結果を返すことができない場合、サーバーは通常これらの値を無視し、エラーコードを返さずに Content-Type で指定された値で結果を返します。Content-Typeレスポンスヘッダーは複数存在することができ、1つは文字セットを識別し、もう1つはMIMEエンコーディングを識別することに注意してください。例: Content-Type: application/json; charset=utf-8 Content-Type: application/jsonl Content-Type: charset=utf-8
Content-Language	レスポンスの自然言語を記述します。これは Accept-Language リクエストヘッダーで指定された言語である必要があります。ただし、サーバーが Accept-Language で指定された値で結果を返すことができない場合、サーバーは通常Accept-Languageを無視し、言語コードまたは国オプション付きの言語コードの値（たとえば、イギリス英語ではなくアメリカ英語の場合は en-US）を返します。eBayでサポートされている値については、「マーケットプレイスIDと言語ヘッダーの値」を参照してください。例: Accept-Language: en-US
Location	POST 呼び出しで新しいリソースを作成する場合、eBayはペイロードを含むレスポンスを返しません。代わりに、レスポンスには新しく作成されたリソースへのURIを含む Location ヘッダーが含まれます。URIを解析してリソースのIDを取得するか、または GET リクエストでURIを使用してリソースのIDを取得できます。
Warning	ステータスコードに反映されない可能性のある、メッセージのステータスまたは変換に関する追加情報を伝達します。

各REST操作で返される可能性のあるHTTPヘッダーの詳細については、各REST操作のドキュメントを参照してください。

注: eBayの呼び出しは複数のレスポンスヘッダーを返します。DTS（Developer Technical Support）に問い合わせる際は、質問のある呼び出しからのレスポンスヘッダーを必ず記録してください。これは、サポートスタッフが参照している呼び出しの詳細を判断するのに役立ちます。

エラーの処理

リクエストの処理中に問題が発生した場合、eBayサーバーはエラーまたは警告状態で応答します。警告が発生した場合は処理が続行されますが、エラーが発生すると処理は停止します。

APIエラーおよび警告レスポンス

リクエストの送信後に受け取る可能性のあるレスポンスコンポーネントには、3つの種類があります。リクエスト処理中に発生した問題に応じて、次のようにエラーまたは警告が返されます。

warnings コンポーネントがあり、errors コンポーネントがない場合: 処理中にエラーは発生しなかったが、1つ以上の警告が発生した場合です。
errors コンポーネントがあり、warnings コンポーネントがない場合: 処理中に1つ以上のエラーが発生した場合です。処理中に警告も発生した可能性がありますが、エラーコンポーネントを含むレスポンスには警告は含まれません。
errors コンポーネントも warnings コンポーネントもない場合: 処理中に警告もエラーも発生しなかった場合です。

返されるエラーオブジェクトと警告オブジェクトは同じタイプ（ErrorData）で、同じフィールドを持ちます。次のセクションでは、3つの可能性それぞれについて、一般的なレスポンスを示します。以下の「エラーおよび警告フィールド値」セクションの表には、リクエスト処理中にエラーまたは警告が発生した場合にレスポンスに含まれる可能性があるすべてのフィールドがリストされています。

警告レスポンス

次の例は、errors コンポーネントのない warnings レスポンスコンポーネントを示しています。

{
  "warnings": [
    {
      "errorId": "long",
      "domain": "string",
      "subDomain": "string",
      "category": "ErrorCategory",
      "message": "string",
      "longMessage": "string",
      "inputRefIds": [
        "string"
      ],
      "outputRefIds": [
        "string"
      ],
      "parameters": [
        "ErrorParameter"
      ]
    }
  ],
  "resource": "Hello, eBay followers!"
}

警告によって処理が停止されないため、HTTPステータスコードが 200 として返されることに注意してください。

エラーレスポンス

warnings コンポーネントのない errors レスポンスコンポーネントを次に示します:

{
  "errors": [
    {
      "errorId": "long",
      "domain": "string",
      "subDomain": "string",
      "category": "ErrorCategory",
      "message": "string",
      "longMessage": "string",
      "inputRefIds": [
        "string"
      ],
      "outputRefIds": [
        "string"
      ],
      "parameters": [
        "ErrorParameter"
      ]
    }
  ]
}

エラーや警告のないレスポンス

最後に、errors コンポーネントも warnings コンポーネントもないレスポンスを次に示します。

HTTP/1.1 200 OK
{
  "resource": "Hello, eBay follower!!"
}

エラーおよび警告フィールドの値

次の表は、errors または warnings コンテナで返される可能性のあるフィールドについて説明しています。

APIエラーおよび警告フィールド

フィールド	タイプ	説明
errorData	オブジェクト	errors または warnings オブジェクトタイプ。
errorData.category	ErrorCategory	このエラーまたは警告のカテゴリタイプ。 ErrorCategory オブジェクトを受け取り、次の3つの値のいずれかを取ることができます。 APPLICATION: アプリケーションコードまたは実行時に例外またはエラーが発生したことを示します。例としては、サービスのビジネスロジックでの例外のキャッチ、システム障害、依存関係からのリクエストエラーなどがあります。 BUSINESS: 「セラーは南極大陸に商品を発送しません」や「バイヤーはアルコール飲料を購入できません」といったビジネスルール違反により、サービスまたは依存サービスがリソースの処理を続行できなかった場合に使用されます。ビジネスエラーは構文入力エラーではありません。 REQUEST: 認証エラー、構文エラー、レート制限、ヘッダーの欠落、不正なHTTPヘッダー値など、リクエスト自体に何らかの問題がある場合に使用されます。
errorData.domain	文字列	サービスまたはアプリケーションを含むドメイン名。
errorData.errorId	数値 (Long)	発生した特定のエラー状態を一意に識別する正の整数。アプリケーションは、カスタマイズされたエラー処理アルゴリズムの識別子としてエラーコードを使用できます。
errorData.inputRefIds	文字列	エラーに関連付けられた特定のリクエスト要素（存在する場合）を識別します。inputRefId のレスポンスは特定の形式です。JSONの場合は、JSONPath 表記を使用します。
errorData.longMessage	文字列	message の拡張バージョン。長さは100～200文字程度ですが、必須ではありません。
errorData.message	文字列	エンドユーザーとアプリ開発者向けの、デバイスに依存しないメッセージです。エラーまたは警告の内容と、その一般的な解決方法を説明します。値は最大50文字です。該当する場合、値はエンドユーザーが要求したロケールにローカライズされます。
errorData.outputRefIds	文字列	エラーに関連付けられている特定のレスポンス要素を識別します（存在する場合）。パスの形式は inputRefId と同じです。
errorData.parameters	ErrorParameter	このオプションの複合フィールドタイプには、コンテキスト固有の ErrorParameter オブジェクトのリストが1つ以上含まれます。リストエントリの各項目は、エラー状態の原因となったパラメータ（または入力フィールド名）です。各 ErrorParameter オブジェクトは、name と value の2つのフィールドで構成されます。
errorData.parameters.name	文字列	エラーが発生したパラメータ/フィールドの名前です。
errorData.parameters.value	文字列	エラーが発生したパラメータ/フィールドの値です。
errorData.subDomain	文字列	ドメインのサブシステムまたはサブディビジョンの名前です。たとえば、「checkout」は「buying」ドメインのサブドメインです。

エラーレスポンスの例

次のエラーは、呼び出しに渡されたパラメータの1つに問題がある場合のサンプルレスポンスを示しています。

{
  "errors": [
    {
      "errorId": 15008,
      "domain": "API_ORDER",
      "category": "REQUEST",
      "message": "Invalid Field : itemId.",
      "inputRefIds": [
        "$.lineItemInputs[0].itemId"
      ],
      "parameters": [
        {
          "name": "itemId",
          "value": "v1|2*********|0"
        }
      ]
    }
  ]
}

一般的なエラー

eBay APIを呼び出すと、上記のようにエラーや警告を含むレスポンスが返されることがあります。ただし、各APIは、API呼び出しの処理中に発生する可能性があるエラー状態である 一般的なエラー を返すこともあります。一般的なエラーは処理を停止するため、呼び出しから正常なレスポンスを受け取る前に対処する必要があります。一般的なエラーでは、個々のインターフェースが使用するのと同じエラーレスポンス構造が使用されます:

{
  "errors": [
    {
      "errorId": "long",
      "domain": "string",
      "subDomain": "string",
      "category": "ErrorCategory",
      "message": "string",
      "longMessage": "string",
      "inputRefIds": [
        "string"
      ],
      "outputRefIds": [
        "string"
      ],
      "parameters": [
        "ErrorParameter"
      ]
    }
  ]
}

以下は、最も頻繁に発生する一般的なエラーの一覧です:

一般的なエラーメッセージ

エラーID	エラーカテゴリ	メッセージ	長いメッセージ	ドメイン	HTTPステータスコード
1001	REQUEST	無効なアクセストークン	無効なアクセストークンです。Authorization HTTPリクエストヘッダーの値を確認してください。	OAuth	401
1002	REQUEST	アクセストークンがありません	Authorization HTTPリクエストヘッダーにアクセストークンがありません。	OAuth	400
1003	REQUEST	「Authorizationヘッダーのトークンタイプが無効です:」+ スキーム	「Authorizationヘッダーのトークンタイプが無効です:」+ スキーム	OAuth	400
1004	REQUEST	内部エラー	アクセストークンの処理中にエラーが発生しました。	OAuth	500
1100	REQUEST	アクセスが拒否されました	リクエストを実行するための権限が不十分です。	OAuth	403
2001	REQUEST	リクエストが多すぎます	リソースのリクエスト制限に達しました。	ACCESS	429
2002	REQUEST	リソースが解決されませんでした	リクエストに関連付けられたリソース（URI）を解決できませんでした。	ACCESS	404
2003	APPLICATION	内部エラー	eBayの内部システムまたはプロセスに問題が発生しました。eBay開発者サポートに連絡して支援を受けてください。	ACCESS	500
2004	REQUEST	無効なリクエストです	リクエストにエラーがあります。ヘルプについては、このAPIのドキュメントを参照してください。	ACCESS	400
3001	REQUEST	リクエストが拒否されました		ROUTING	400
3002	REQUEST	不正なリクエストです	リクエストにエラーがあります。ヘルプについては、このAPIのドキュメントを参照してください。	ROUTING	400
3003	REQUEST	リソースが見つかりません	リクエストに関連付けられたリソース（URI）を解決できませんでした。	ROUTING	404
3004	APPLICATION	内部エラー		ROUTING	500
3005	APPLICATION	内部エラー		ROUTING	502

HTTPステータスコードの詳細については、「HTTPステータスコード」を参照してください。

バージョン管理とAPIライフサイクル

各APIは APIライフサイクル を経て、リリース、更新、そして最終的には廃止というさまざまな段階を経ます。

APIのバージョン管理

eBay RESTful APIには、バージョン番号の3つの部分があり、各部分はピリオド (".") で区切られています。たとえば、バージョン1.0.0はAPIの最初のリリースを示し、APIのそれ以降のリリースでは、バージョン番号の1つ以上の部分が更新されます。小数点に似ていますが、バージョン番号の3つの部分のいずれかまたはすべてが9より大きくなることがあります。たとえば、1.12.47は有効なバージョン番号です。

3つのバージョン番号の部分は、リリースのメジャー、マイナー、メンテナンスバージョンとして定義され、各バージョン番号部分はAPIの異なる種類の変更を表します。これにより、バージョン1.3.7のAPIは、メジャーバージョン1、マイナーバージョン3、メンテナンスバージョン7であると解釈できます。

新しいバージョンのAPIの処理方法を示すために、次のリストにバージョン1.3.7から始まる一連の更新の概要を示します。

バージョン1.3.8 では、3番目のバージョン番号が増加します。これは、以前のバージョン（バージョン1.3.7）に適用された下位互換性のあるバグ修正または同様の更新の メンテナンスリリース です。
- この変更は、バージョンが更新されたことに気付く以外、ユーザーに影響はありません。コードを変更する必要はありません。
バージョン1.4.0 では、マイナーリリース 番号が増加します。これは、バージョン1.3.8に適用される新しい下位互換性のある機能を表します。
- APIには、追加のレスポンスフィールド、新しいオプションパラメータ、新しいコマンドなどが含まれるようになりました。既存のコードでAPIを引き続き使用できますが、APIの新機能を使用するには更新する必要があります。
バージョン2.0.0 は メジャーリリース です。メジャーリリース番号が増加し、他のバージョン番号はゼロクリアされます。メジャーバージョンリリースには、APIの以前のリリースからの 下位互換性のない APIの変更が含まれます。
- APIでメソッドが廃止され、新しい必須パラメータなどが追加されました。新しいバージョンで動作するように、API呼び出しURIなどのコードを更新する必要があります。ただし、少なくともしばらくの間は、コードを変更せずに古いバージョンを引き続き使用できます（eBayのバージョン廃止ポリシーについては、以下を参照してください）。
- メジャーバージョンの変更では、そのAPIを呼び出すために使用するURIを変更する必要があります。「REST操作のURI」で説明されているように、操作のURIにはAPIのメジャーバージョン番号が含まれます。

APIのリリース段階

eBayでは、APIと開発者向け製品のリリースに Alpha 、Beta 、General Availability (GA) の3つの段階があります。リリース段階に加えて、APIには Experimental（試験的）リリースもあります。Experimentalは、Alpha、Beta、GAと同じ意味でのリリースフェーズではありません。成熟モデルを表すものではなく、3つのリリース段階のいずれでも発生する可能性があります。

次の表に、各リリースタイプの目的と使用方法をまとめます。

特性	アルファ	ベータ	一般提供 (GA)
目的と利点	目的は、API機能と機能要件のテストと開発です。将来のeBay API機能をプレビューして影響を与える機会です。	目的は、フィードバックを得るためにAPI機能をリリースすることです。GAの前に新しいAPIに早期にアクセスする機会です。	目的は、実稼働環境での使用のためにAPI機能をリリースすることです。
アクセスできるユーザー	NDAを締結した一部のeBay開発者プログラムメンバーが利用できます。	すべてのeBay開発者プログラムメンバーが利用できますが、資格基準が適用される場合があります。	すべてのeBay開発者プログラムメンバーが利用できますが、資格基準が適用される場合があります。
提供されるサポート	サポートはアカウント管理サポートによってのみ提供され、正式なドキュメントがない場合があります	標準のテクニカルサポートチャネルが利用可能で、ドラフトドキュメントが用意されています。	完全なドキュメントが用意された標準のテクニカルサポート。
API設計の安定性	APIはアルファテストのフィードバックによって変更される可能性があり、ベータ版はアルファ版と下位互換性がない可能性があります。	ベータ期間中にAPIが変更される可能性があり、GAはベータ版と下位互換性がない可能性があります。	安定したインターフェース設計。
品質	重大な設計および可用性の問題がある可能性があります。	設計および可用性の問題がある可能性があります。	実稼働レベル。
使用目的	テスト環境または限定的な使用のテスト。	限定的な実稼働使用ですが、ビジネスクリティカルな用途には使用しないでください。	実稼働。
顧客オンボーディングに使用できますか?	いいえ	はい	はい
負荷テストに使用できますか?	いいえ	いいえ	はい

限定リリースAPI

eBay RESTfulパブリックAPIまたは特定のAPIメソッドは、すべての開発者が使用できるわけではありません。これらの機能は、限定リリース として指定されています。eBayでは、これらのAPIおよびメソッドへのアクセスを、eBay、eBayのバイヤーとセラー、およびeBay開発者コミュニティに最大の価値を提供する開発者/アプリケーションに制限しています。限定リリースAPIにアクセスするには、eBayからの招待、および/または厳格なビジネスケースレビューと契約書の締結が必要です。

注: 限定リリースは、ベータ版やGAなどのリリースフェーズではなく、APIが成熟していることを意味します。ただし、リリースフェーズは限定リリースAPIに適用されます。つまり、限定リリースAPIは、実験版やGAなど、どのリリースフェーズにあってもかまいません。

すべてのRESTfulパブリックAPIと同様に、アクセスはスコープによって制御されます。アプリケーションが限定リリースAPIの使用を承認されると、必要なスコープが利用可能になり、必要な権限を持つアクセストークンを生成できるようになります。アクセスできるかどうか、またどのようにアクセスできるかについては、APIのドキュメントを参照してください。

試験的（Experimental）API

eBayの試験的APIの目的は、テストと調査です。eBayでは、試験的リリースを使用して新しいビジネス機能や機能をテストし、影響を分析します。試験的APIはリリースフェーズに結び付けられておらず、eBayは完全な成熟度（つまりGAリリース）まで改良または提供する義務はありません。

試験的リリースは、完全なAPI、個々のリソース、またはメソッドに適用される場合があります。試験的なリソースまたはメソッドは、3つの開始フェーズのいずれでもAPIに追加（または削除）できます。

注: 試験的だからといって、品質が低い、サポートがない、パフォーマンスが悪いということではありません。試験的は、ベータ版やGAなどのリリースフェーズではないため、APIが成熟しているわけではありません。ただし、試験的APIに対する変更は下位互換性がない場合があり、いつでも発生する可能性があります。APIまたはインターフェースは予告なく削除される場合があります。自己責任でご使用ください。

試験的APIは、限定的な本番環境での使用には適していますが、ビジネスクリティカルな用途には適していません。試験的APIへのアクセスには、資格基準が適用される場合があります。詳細については、APIのドキュメントを参照してください。

eBayの廃止ポリシー

eBayでは、以前のすべてのバージョンと互換性のあるAPIの更新を行うよう努めていますが、APIが古くなり、顧客に優れたサービスを提供するためにeBayがAPIを廃止しなければならない場合があります。廃止期間中も、APIエンドポイントは引き続き利用できます。廃止の詳細は、「APIの廃止ステータス」ページに記載されています。

アプリケーション開発のサポート

開発プロセスに役立つサポートリソースについては、「サポートを受ける」を参照してください。

eBay機能情報

eBayアプリケーション開発を直接サポートするリソースに加えて、次のリソースで追加の詳細が提供されます。

eBayコミュニティ

最後に、eBayコミュニティ はeBayがホストする、ユーザーが交流し情報を共有できる場所です。eBayユーザーによって提供され、eBayユーザー向けに配信される最新のeBayニュースを入手するには、eBayコミュニティに参加してください。

eBayコミュニティ

eBayでサインイン

eBayでサインインオプションを提供することで、優れたユーザーエクスペリエンスを実現できます。詳しくは、「eBayでサインイン統合ガイドライン」をご覧ください。