API Basics
Introduction
The Hip eCommerce API provides a simple RESTful interface with lightweight JSON-formatted responses to use many of Hip eCommerce's websites features, including public Listings, Stores, and Sales (Orders), using API Keys to allow both read and write access to users' public and private data. This document provides information to developers on how to integrate with the Hip eCommerce API.
Accessing the API
The Hip eCommerce API is accessed via the /api directory within the primary domain of each of our marketplaces:
HipStamp: https://www.hipstamp.com/api
HipPostcard: https://www.hippostcard.com/api
HipComic: https://www.hipcomic.com/api
A sample unauthenticated request might look like:
GET https://www.hipstamp.com/api/listings/active?api_key={YOUR_API_KEY}
To retrieve recent active listings on HipStamp.
API requests must use HTTPS, HTTP requests will result in 400 Bad Request responses.
Authentication
The Hip eCommerce API requires an application key that is provided during
app registration. The key identifies your application to the Hip eCommerce web service, and is used to track overall call usage. It's passed using the standard api_key parameter, or alternatively through the X-ApiKey header in your request.
New users register an application and receive a provisional API key upon signup. These keys have full access to resources in the Hip eCommerce API, however they are restricted to allow authentication only for the user who registered the application.
Rate Limiting
Clients are allowed 10,000 requests per 24-hour period, with a limit of 10 queries per second, per API key.
If your application needs more than the allotted number of calls, Contact Us with a description of the application and an estimate on needed call usage. You might also want to investigate the use of caching to keep the number of calls to a minimum, and make your application more responsive.
Headers: Every API response bears rate limit headers, as described below:
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9650
These default rate limits are subject to change at any time, without notice.
API Requests
The Hip eCommerce API uses a RESTful calling style that works with standard HTTP calls. Any web programming language (PHP, Perl, Python, Java...) should be able to make and receive HTTP networking calls; consult the documentation for your language of choice.
Request URLs
In a RESTful API, each resource or collection of resources is identified by a unique URL, such as:
https://www.hipstamp.com/api/listings/:id
URL paths contain the unique IDs of resources. These are identified by a leading colon, as with :id above. Before making a call, you must substitute a valid ID value for these placeholders. ID parameters must appear in the URL and cannot be substituted for GET parameters. All ID parameters listed in the URL pattern must be present.
Output Formats
The Hip eCommerce API returns data in JSON format.
HTTP Methods
RESTful APIs use standard HTTP methods to denote actions against a resource:
GET - Reads a resource. Returns HTTP 200 on success.
POST - Creates a new resource. Returns HTTP 201 on success (or 200 if a resource was updated).
PUT - Updates a resource. Returns HTTP 200 on success.
DELETE - Deletes a resource. Returns HTTP 200 on success.
Because some toolkits lack support for PUT and DELETE (most notably JavaScript) you can use method overloading to fake an HTTP method. Use a GET or POST call and append the standard _method parameter:
https://www.hipstamp.com/api/listings/12345?_method=DELETE
Parameter Types
Many API methods take one or more parameters. The default way to provide these parameters is either as query parameters of the URL itself, or as POST parameters. However, for POST and PUT requests, we do offer two additional ways in which you can supply parameters; through a JSON object, or an XML object (with a dummy root node).
To provide a JSON object, or an XML object (with a dummy root node), you must set the Content-Type header in your request as follows, respectively:
Content-Type: application/json
Content-Type: application/xml
If you are using the default way to provide parameters (either as query parameters of the URL itself, or as POST parameters), you may leave the Content-Type blank, or utilize either of the following:
Content-Type: text/plain
Content-Type: multipart/form-data
The documentation for each method references these standard types:
Param Type
| Meaning
|
string
| Any string. Max 255 characters, unless otherwise specified.
|
int
| A whole number value.
|
time
| A time in the format YYYY-MM-DD HH:MM:SS or any string accepted by PHP's strtotime() function. Note that all times are Eastern Standard / Daylight.
|
float
| A number with or without a decimal point. May be represented in output as a string to avoid precision errors.
|
boolean
| A logical true or false value. May be passed to API requests as a "1" or "0". In JSON output, "1" or "0" will be used.
|
username
| A user's username (not the same as a Store name)
|
enum(values)
| A predefined list of string values, for example "black" and "white". Any value not in the list may result in an error. If values are not specified, review the description of the field for additional information on acceptable values.
|
array(type)
| A list of values, separated by two pipe characters || Each value must be a valid instance of type. (See Array notes below).
|
json_array(type)
| A JSON array object. (See JSON Array Object notes below.)
|
url
| A string representation of a valid URL.
|
currency
| A 3-letter ISO 4217 code.
|
Array Notes
When providing parameters via the standard way of the URL itself, or as POST parameters, arrays are represented as strings, with values separated by two consecutive pipe characters (ASCII code 124). For example, when creating a new listing, here are values for the images parameter, expressed as an array:
https://www.example.com/12345.jpg||https://www.example.com/uploads/12357.jpg
As previously noted, for POST and PUT requests, you can optionally supply parameters through a JSON object, or an XML object (with a dummy root node). In these cases (and again with the appropriate Content-Type header set) you can represent array data as it would be represented within a JSON object or XML. For example:
Content-Type: application/json
images: [
"https://www.example.com/uploads/12345.jpg",
"https://www.example.com/uploads/12357.jpg"
]
Content-Type: application/xml
<images>
https://www.example.com/uploads/12345.png
<images>
https://www.example.com/uploads/12357.png
JSON Array Object Notes
As the response format for the Hip eCommerce API is JSON data (see below), there is no difference between a standard array object and a JSON array object in the response sent. However, there is a difference between an array and a json_array when it comes to sending a request to the Hip eCommerce API. When providing parameters via the standard way of the URL itself, or as POST parameters, an array can be expressed by separating values with two pipe characters || However, there are some fields, most notably postage, which are more complex and can not be expressed in this way.
In these cases, you must use a JSON object to represent the value of the parameter. For example:
"postage": [
{
"price": "2.50",
"price_addl": "0.50",
"method": "First Class",
"location_groups": [ "Domestic" ]
},
{
"price": "4.50",
"price_addl": "0.75",
"method": "First Class",
"location_groups": [ "Everywhere Else" ]
}
]
This is true even when providing parameters via the standard way of the URL itself, or as POST parameters. However, if you submitting parameters via XML, you may supply an equivalent XML node instead, as shown in the following example:
Content-Type: application/xml
<postage>
<location_groups>Domestic</location_groups>
<method>First Class</method>
<price>2.50</price>
<price_addl>0.50</price_addl>
</postage>
<postage>
<location_groups>Everywhere Else</location_groups>
<method>First Class</method>
<price>4.50</price>
<price_addl>0.75</price_addl>
</postage>
Standard Parameters
Here is a list of standard parameters that are accepted by many or all API methods:
Param
| Type
| Meaning
|
api_key
| string
| Your API key. Required for all calls (unless set in the X-ApiKey header).
|
_method
| string
| Used to specify a custom HTTP method for method overloading.
|
limit
| int
| Specifies the maximum number of records to return. Default is 25.
|
page
| int
| Skips the first ((N-1) * limit) records before returning results. Combine with limit for pagination. Default is 1.
|
JSON Data
Data is returned using
JSON, a lightweight serialization language that is compatible with many different languages (such
json_decode in PHP). JSON is also syntactically correct JavaScript code, which means that it can be parsed with JavaScript's own eval() function.
Standard Response Format
Each API response is wrapped in a standard structure that holds the results of the API call, plus metadata about the request:
{
"count": integer,
"type": result type
"results": [
{ result object }
],
"params": { parameters },
}
count specifies the total number of results available for this call, which may be more than the number of results returned in this request. For example, if count is 1000, you can page through the results in blocks of 100 by specifying limit=100&page=1, where page is 1 thru 10. See Pagination below.
results is an array of results. For consistency's sake, it is always an array, even if only one result is expected.
params echoes the parameters that were passed in the request.
type specifies the type of the objects in the results array. (See the individual pages under "API Reference".)
notices is an array of notices. This will only be returned when there are notices. An example of a notice would be when creating or updating a Listing, if you specify a title which is longer than 80 characters, your Listing will be accepted, but the title will be truncated to 80 characters. This will be included as a notice.
errors is an array of errors. If an error occurs, the appropriate response headers will be set via HTTP status code. However, a detailed explanation of any errors will be included in the errors array. This will only be returned when there is an error, and in which case neither count, results, params, type or notices will be returned.
Associations
As noted above, individual pages under "API Reference" detail the types of objects which may be returned in results. Each page will detail the Field Names of the fields which are returned - which will general be lowercase (unless otherwise noted). Objects may also contain Associations, which will be objects of another type attached to the main object. Pay special attention to the fact that the names of these attached objects will generally be uppercase. For example, take a look at this snippet of a Listing result, with a Bids object attached:
"currency": "GBP",
"quantity": "1",
"start_price": "5.00",
"Bids": [
{
"user_id": "109400",
"amount": "35.00",
"outbid": "0",
"created_at": "2017-11-16 10:41:51"
}
],
Pagination
The default records returned per call is 25, and the maximum number that can be returned is 100. We provide limit and pageparameters to allow navigation through larger data sets. Responses include a count field, which specifies the total number of records available via pagination. For performance reasons, the combination of (limit * page) is limited to a maximum value of 50000; except when accessing Listings which belong to the current User, in which case it is limited to a maximum value of 1000000.
Here's an example of sequential requests to paginate through 200 recent active listings, 50 at a time:
https://www.hipstamp.com/api/listings/active?limit=50&page=1
https://www.hipstamp.com/api/listings/active?limit=50&page=2
https://www.hipstamp.com/api/listings/active?limit=50&page=3
https://www.hipstamp.com/api/listings/active?limit=50&page=4
Standard Response Codes
The Hip eCommerce API uses standard HTTP status codes to indicate success or failure of API calls (consult the documentation for your programming language to learn how the read the status code of an HTTP call).
HTTP Code
| Message
| Meaning
|
200
| OK
| Success!
|
201
| Created
| A new resource was successfully created. Note the JSON response will return the newly created resource in the results parameter of the body.
|
400
| Bad Request
| You've made an error in your request (such as passing a string for a parameter that expects a number).
|
403
| Forbidden
| The data you're trying to access is private.
|
404
| Not Found
| The requested resource could not be found, or the URI doesn't correspond to any known command.
|
405
| Method Not Allowed
| A request method is not supported for the requested resource (such as trying to close a Listing which is already closed).
|
429
| Rate Limit Exceeded
| You've exceeded the rate limits for your account.
|
500
| Server Error
| An internal error on our side. If this problem persists, please Contact Us.
|
The errors parameter within the response (see above) will contain a detailed description of many errors.
Tip: What's the difference between a 404 Not Found and a 200 OK with empty results? If you're searching for a specific record, say listing #654864, and it doesn't exist, that's a 404 Not Found. However, if you're searching for a set of records and no listings match your search, that's a 200 OK. There's nothing wrong with your request, but it doesn't match anything, and your result set is empty.
This might seem a little arbitrary, but it makes practical sense: search engines typically don't display an error page if your search comes up empty. On the other hand, trying to access a URL that doesn't exist will turn up a standard 404 error page. Your application will probably have similar behavior.