eBay APIs are now written to be RESTful. This guide explains the high-level REST call and response mechanics. It also provides other information that you'll need as you write applications with the eBay APIs (including how to generate OAuth tokens and how to parse error messages).
This guide lives at the top level of the REST doc hierarchy, and should be read before you work with the individual APIs.
What is REST?
REST stands for REpresentational State Transfer, which probably doesn't help you that much in understanding what it is. Pragmatically, it means that you or your program communicates with a remotely-run service using standard web commands and protocols such as HTTP requests and responses. You send the service an API command wrapped in an HTTP request, and it responds with a success or failure indicator and any results data, all wrapped in an HTTP response.
This means the REST API itself is stateless. State is maintained on either the client side or the service side, but not within the API. Thus the full name; Representational State Transfer. REST APIs transfer state from client to server or vice versa.
Benefits of using REST
A key benefit of REST is that HTTP is widely used. Plus, sending and receiving HTTP requests and responses doesn't take much bandwidth.
In addition, the syntax and protocols used by REST (JSON and the URI addressing protocol) are well known and baked into how you already use the web. The underlying system has already been built and installed, and it's available for anyone to use. This minimizes the amount of work users and developers have to do to get their applications up and running. In theory, all RESTful APIs have the same, easy to learn, interface format.
REST architecture emphasizes that interactions between clients and services are enhanced by having a limited number of operations with which it acts. Specifically, there are four common HTTP methods that give you full "CRUD" capabilities: Create, Retrieve, Update, and Delete. Each of the main HTTP methods (GET, POST, PUT, and DELETE) has a specific meaning in the REST architecture, and in this way REST avoids ambiguity. You can think of the HTTP methods as the verbs in a rest operation.
For flexibility, we assign resources their own unique Universal Resource Identifiers (URIs). Resources are the nouns in a REST operations, and often consist of either a single entity, or a group of like entities.
The topics in this guide cover the following information:
- Creating a developer account — How to join the eBay Developers Program.
- Making a call — How to make calls to the eBay APIs in 3 steps.
- OAuth Access Tokens — eBay's REST interfaces use OAuth 2.0 access tokens for application authentication and user authorization. This topic tells you how to get, use, and refresh access tokens.
- Request Components — What makes up a REST request, and how you put one together.
- Response Components — What makes up a REST response, and how you parse and interpret it.
- Handling Error Messages — This topic describes eBay's common format for how HTTP responses return error and warning messages.
- OpenAPI and eBay RESTful APIs — An overview of OpenAPI, and how to use its associated Swagger tools to generate client libraries for eBay APIs in multiple programming languages.
- Using API Explorer to run sample calls — API Explorer is a tool that lets you run sample calls for all the methods in the eBay APIs.
- Testing in the Sandbox— How to test your application in the eBay Sandbox, a self-contained testing environment that doesn't affect live listings, user accounts, or bank accounts.
- Versioning and API lifecycle— Each API travels through the API lifecycle, where it goes through the different stages of release, updates, and eventually deprecation.
- Security and Your eBay Apps — What data needs to be secured, both on the client and service sides, and how it is secured on the service side and how you should secure it on the client side.
- Support for application development — Where and how to get help if you have problems developing your application.