Getting Started

The Solver API (SAPI) is a front-end for the D-Wave quantum processing unit (QPU) solver[1] and a variety of other advanced software solvers. A REST-based web services API, SAPI is used internally by D-Wave client applications.

[1]A solver is simply a resource that receives a problem and returns an answer; it may be a D-Wave QPU or a software emulation of one. See D-Wave Solver Properties and Parameters: Reference for more information.

SAPI allows you to formulate a wide range of problems amenable to quantum acceleration. The API is fairly simple to use; it exposes only a few basic calls. Most of the work for you will be restructuring your problem into a format that the API can answer, and then parsing results.

What is REST?

REST, which stands for Representational State Transfer, is a lightweight web services protocol. It came into being as a response to heavyweight Web services protocols such as SOAP and XML-RPC, which rely on a predefined messaging format and methods to pass them back and forth between servers and clients. REST, on the other hand, specifies no such limitations; you can use any message format that you like (whether it be JSON, XML, HTML, serialized data, or even straight text), and operates on the standard HTTP verbs of GET, DELETE, and POST for its operations.

The rules that exist for REST client/server interactions can be completely defined by the application requirements. So if you define a REST interface that is intended to be consumed by a JavaScript client, you probably want to have the data returned in a JSON format, while if you intend for the data to be consumed by a PHP client, then perhaps serialized data or XML is a better choice.

Each REST web services call is a simple HTTP request, using one of the standard HTTP verbs:

  • GET—Retrieve data from a server
  • POST—Send data to a server
  • DELETE—Delete a resource from a server

HTTP Response Codes

Table 22 HTTP Response Codes
Code Explanation
200 OK No error.
201 CREATED Creation of a resource was successful.
202 ACCEPTED Problem cancellation request was received.
304 NOT MODIFIED The resource hasn’t changed since the time specified in the request’s If-Modified-Since header.
400 BAD REQUEST Invalid request URI or header, or unsupported nonstandard parameter.
401 UNAUTHORIZED Authorization required. This error can also mean that incorrect user credentials were sent with the request.
403 FORBIDDEN Unsupported standard parameter, or authentication or authorization failed.
404 NOT FOUND Resource (such as a problem) not found.
409 ALREADY TERMINATED Problem reached one of terminal states before the call.
429 TOO MANY REQUESTS API request rate exceeds the permissible limit.
500 INTERNAL SERVER ERROR Internal error. This is the default code that is used for all unrecognized server errors.

Setup

Examples in this document use curl to send HTTP requests to the SAPI web service. Set the base URL and the API token environment variables to the home URL of the SAPI web service and an API key on the server hosting the web service respectively.

For example:

export SAPI_HOME=https://cloud.dwavesys.com/sapi
export SAPI_TOKEN=ProjectA-tokens-string

Note

All URLs referenced in the documentation have the following base: https://cloud.dwavesys.com/sapi. This API endpoint can vary based on the system setup and is referenced throughout the document as SAPI_HOME.

Authentication and Access

All requests to SAPI require users to authenticate using an API token. API tokens are associated with projects. Each project has a priority and one or more solvers that users who are assigned to that project can access. Each problem that SAPI accepts is authenticated via the token and sent to a solver for solution. API tokens do not differentiate between solvers in their project.

An API token is sent to SAPI in the form of HTTP header X-Auth-Token. A simple example of getting list of remote solvers using curl is as follows:

SAPI_HOME=https://cloud.dwavesys.com/sapi
SAPI_TOKEN=ProjectA-tokens-string
curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/solvers/remote/

Projects and individual users may have quotas configured, which control solver access time.

Data Store

While some problem data is cached, the SAPI server itself is an I/O queue rather than a database. While it has a short-term Redis-based data store, the server does not store solutions long-term. Therefore, it is good practice to periodically retrieve the solutions you want to keep. Expiry times vary by system; plan to retrieve results within a couple of hours after your problem completes.