The Solver API (SAPI) is a front-end for the D-Wave quantum processing unit (QPU) solver and a variety of other advanced software solvers. A REST-based web services API, SAPI is used internally by D-Wave client applications.
|||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.
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¶
|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
|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.|
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.
export SAPI_HOME=https://cloud.dwavesys.com/sapi export SAPI_TOKEN=ProjectA-tokens-string
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
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
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.
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.