View source for Using the API

The Spiffy Stores API is a RESTful web service.

=== Authentication ===

The API uses HTTP Basic Authentication to allow private applications to connect to a store using an API key generated by that store.

It also uses OAuth 2 protocol to authenticate 3rd-party applications which can connect to any store which grants the application permission to do so.

=== Calling the API ===

The Spiffy Stores API only supports JSON-encoded data as requests and responses. You will need to set both the <code>Content-Type</code> and <code>Accept</code> headers to <code>application/json</code> to identify the request and response format.

==== Using Private API Keys ====

You can call an API using a private API key and password with a URL in the following format:

<pre>
https://API_KEY:API_PASSWORD@STORE_NAME.spiffystores.com/api/RESOURCE.json
</pre>

In the above example, replace <code>API_KEY</code> with the API key you generated for this application, and <code>API_PASSWORD</code> with the associated password.

Use your short store name instead of <code>STORE_NAME</code>. Your short store name is the same as the name used in the URL for your Spiffy Stores Toolbox.

Replace <code>RESOURCE</code> with the appropriate resource parameters that you need for the particular API that you are calling.

For example, in order to get details about the store, you would issue a GET request using a URL similar to the following:

<pre>
https://71a8...83e5:2e47...7e1f@storedemo.spiffystores.com/api/store.json
</pre>

=== API Usage Limits ===

The Spiffy Stores API is subject to rate limiting in order to protect the server and all the web-facing stores from being flooded with service requests.

The exact parameters of the rate limiting are subject to change from time to time, but are set to allow a generous amount of requests to be processed in a reasonably short period.

If at any time you experience requests being rejected due the number of requests exceeding the server limits, then please contact us to discuss your needs.

The current API usage limits are reported on each call in the response header <code>X-Ratelimit</code>. The usage data is returned in JSON format, and provides the limit, number of calls remaining and the time at which the limit is reset.

<pre>
X-Ratelimit: {"name":"API","period":300,"limit":500,"remaining":496,"until":"2014-11-28T03:45:00Z"}
</pre>

=== Dates and Times ===

All dates and times generated by the API are in UTC.

== Further Reference ==

* [[An Introduction to the Spiffy Stores API]]
* [[Creating Private API Keys]]
* [[API Reference]]