GraphQL is a query language released as an open-source project that provides an efficient and flexible API architecture. You can create and execute queries by using a type system you define specifically for your data. For additional information about using GraphQL as a client, see Introduction to GraphQL.

The eBay GraphQL is served and consumed over HTTP. This maximizes compatibility for clients, servers and tools, and aligns closely with the draft specification GraphQL over HTTP.

Benefits

GraphQL is particularly beneficial where bandwidth is a concern or flexibility is important:

• Declarative data fetching: Clients can request exactly the data they need, nothing more and nothing less (eliminates over-fetching or under-fetching data)
• Single endpoint: Exposes a single endpoint which handles a wide variety of queries and mutations.
• Strongly typed schema: Defined by a schema that specifies the types of data, which serves as a contract between the client and server.
• Efficient data loading: Optimizes data retrieval by allowing clients to specify their data requirements which reduces the amount of data transferred over the network and improves application performance.
• Flexibility and evolution: Enables APIs to evolve without breaking existing queries. New fields and types can be added to the schema without impacting existing clients.

Authorization

Clients must provide a valid token in the Authorization header. To understand which OAuth scope to use to access objects, queries, and mutations in GraphQL, refer to the specific eBay GraphQL API's reference documentation.

For information on how authorization works for eBay APIs, see the Authorization Guide.

Request components

Query

Each query must be a POST request (GET requests are not accepted) and contain the required request headers and the request body. Also, make sure the request contains the query in a serialized string (required for GraphQL over HTTP). See Request body for more information.

Mutation

Each mutation must be a POST request and contain the required request headers and the request body. Also, make sure the request contains the query in a serialized string (required for GraphQL over HTTP).

Request headers

All requests made to the eBay Public Federated GraphQL Gateway operations require you to provide the Authorization HTTP header for authentication authorization. You can find general information about HTTP request headers used by eBay in HTTP request headers.

The following request headers are required by eBay GraphQL operations:

Request body

The request body, often called a payload, is typically required for both operationtypes, which include queries (retrieving information) and mutations (creating, updating, or deleting information). In the eBay GraphQL APIs, all request payloads and response payloads are formatted in JSON. See the GraphQL API reference documentation for definition of the fields supported in the body for each operation.

The following code shows an example JSON payload for an eBay GraphQL mutation operation, a call that initiates a process that uses seller provided external product data to create an eBay Listing Preview and returns its id. The request defines the query and also any variables to use. The query includes a serialized string defining the Operation type, Operation name, Variable definitions, and also any returned fields such as id. The variables include definitions for values for any variables defined by the operation in its Variable definitions. The eBay GraphQL does not provide for extensions in the request, but may return them for errors in the response (see Extension object format).

Input variables

We support GraphQL input arguments only through variables. Inline/literal input values within the GraphQL operation are not supported.

Supported

query GetItem($itemId: ID!) {
  item(id: $itemId) {
    title
  }
}
{
  "itemId": "123456789"
} 

Not supported

query {
  item(id: "123456789") {
    title
  }
}

Using variables keeps the GraphQL operation separate from request-specific data. This promotes operation reuse, consistent input validation, cleaner handling of complex inputs, and avoids dynamically constructing query strings. The GraphQL specification also recommends variables for parameterizing reusable operations and avoiding runtime string construction.

For more information about input variables, see Graph QL - Variables.