A. We are happy to assist in making sure every dealer has access to our data through our API; however, as a business rule, we generally don’t assist with how to implement the data into a particular system. There are simply too many different databases, shopping carts, and other software environments for us to provide support for them all. A lot of dealers ask us how to import the provided data directly into their database and there just isn’t a simple process for that. There will always be some degree of integration code dealers will need to write to import our data into their database. The data format we use was not created to be conducive to any specific Database Management System (DBMS). Therefore in order to get the data into a particular system the first step is to request it from us, store it, parse it, and format it in a way that’s conducive to import into the particular database.

A. At this time, we do not provide any application or mechanism to consume our data. We’ve been asked numerous times if we could share examples or code snippets of how we built our sites and how we consume our own data. Unfortunately, our sites are fairly custom-built and don’t use standard off-the-shelf software. If we were to share our code, it probably wouldn’t help you much.

A. In the future we may provide a service or some kind of all-inclusive web solution that we can put in the hands of our dealers and let them run with it. But right now we merely provide the data; it is up to the individual dealers what they do with it.

A. Our API is designed to provide the necessary data for experienced programmers to consume, store, and integrate into their system. The data we provide are in a language-independent data-interchange format so that almost any programming language can be used to request and consume the data. The format we use is JSON which is not specific to any platform, programming language, or web system.

A. All timestamps are in the Coordinated Universal Time (UTC) +0000 UTC standard. UTC can be assumed on all dates that are returned from the API such as created_at and updated_at.

A. Recently it was brought to our attention that there may be some confusion regarding differing return types from the API. We'd like to take this opportunity to clarify some of the confusion and hopefully save you some time when dealing with the parsing of various responses.

The flexibility of being able to send multiple IDs separated by a comma with a GET request is nice, but it introduces two different data types of results. If you specify just one ID then you get a record {"data": {...}} but if there is more than one ID you get an array {"data": [{...}...{...}]}. This can make parsing into the right object difficult.

The thing to remember is the differing return types is a result of what you're actually returning, an entity or collection. Let's use some examples...

1. All Attributekeys

   https://api.wps-inc.com/attributekeys

   Returns {"data": [{...}...{...}]}, a multiple-entity collection response which makes sense to be an "array".

2. One Attributekey

   https://api.wps-inc.com/attributekeys/15

   Returns {"data": {...}}, a single entity response which makes sense to be an "object" and will never be an array. It wouldn't make sense to be an array with ever only one element.

3. A set of Attributekeys filtered by the 'updated_at' date

   https://api.wps-inc.com/attributekeys?filter[updated_at][gt]=2017-07-25

   Returns {"data": [{...}...{...}]}, a multiple-entity collection response which makes sense to be an "array" because you are just filtering a collection by the `updated_at` date.

4. A set of Attributekeys filtered by IDs

   https://api.wps-inc.com/attributekeys/15,17

   Returns {"data": [{...}...{...}]}, a multiple-entity collection response which makes sense to be an "array" because you are just filtering a collection to those specific Id's.

   When you make the above request, what you are really doing is just a shortcut for...

   https://api.wps-inc.com/attributekeys?filter[id]=15|17

   ...They both return the exact same thing.

   So, because our API is so flexible and there are so many ways to query the data, it is really just a matter of the type of response you'd like to receive. If you want to clearly separate the two return types, stick to standard entity responses where you can expect an object (ie. https://api.wps-inc.com/attributekeys/15), and collection requests that utilize "filter" where you can expect an array.

   The confusion lies in the tricky little helper where you can send multiple IDs separate by a comma (ie. https://api.wps-inc.com/attributekeys/15,17). That type of request is obviously throwing people off. We're even considering leaving that trick out of the documentation to avoid confusion. What you need to understand is that #2 and #4 in the above examples are not the same thing. They are two very different ways of querying the API.

A. We often get issues reported when API users figure out that they can just crank up the page[size] parameter to get more results. When making requests that may return extremely large results, typically by using obscene parameters like ?page[size]=999999 you may experience results with an HTTP status code of 504 Gateway Time-out.

As most of you are aware, the results in our API come back in a cursor-based fashion so you can just adjust the page[size] parameter to increase the number of results you receive back. The caveat to this is you can potentially request such a large result that the request times out. This can even be due to the limitation of your Internet and/or bandwidth. So, the takeaway is the old saying "just because you can... doesn't mean you should." There comes a point where requesting more isn't necessarily a good thing. Make smaller requests and more of them rather than fewer, larger requests.

A. The API does not necessarily have any rate limiting or throttling. The only real limitation is the various hardware, programming, and network factors that can all affect speed and timeouts. That said, what it does have is a hardware limit of a given node in our cluster that handles a particular request. We're set up in a load balanced configuration so that all your requests are handled quickly by a swarm of servers. However, there are limits to what a single request to a single node is designed to handle.

Case in point, when making Item requests with parameters like this...

?include=vehicles.vehicleyear,vehicles.vehiclemodel.vehiclemake,vehicles.vehiclemodel.taxonomyterms,product.features,product.resources,attributevalues.attributekey,brand,country,images,taxonomyterms&page[size]=1000

...our webservers would cut your request off prematurely when it reached a certain number of megabytes of memory; whatever we have the limit currently set to. Yes, that single request contained so much data that the server refused to hold that much in memory to serve it up and we chopped it off intentionally, by design. This often results in an HTTP status code of 500 Internal Server Error. Yes, we could bump up hardware resources to handle this, but we're not going to. Our feelings are that if you're making such a large request that it overruns our memory cap, your request SHOULD be cut off. That is your indication that you're doing it wrong. Make smaller requests. Don't try to grab our whole database in one request; that is not how API's work.

A. Years ago, we provided dealers with a categorization of sorts, but it was essentially the structure of our printed catalogs. We later realized that our catalog categorization didn't always suit dealers needs and/or make sense to display items on the Internet in the same fashion. We were constantly changing the catalog categorization to fit the needs of the printed catalog year-to-year, often times making specific adjustments that didn't always make sense for dealers to follow on their websites. The decision was made in the latest iteration of our API (Version 4) to leave our printed catalog categorization out of the API. It simply didn’t make sense to have all dealers design their websites in the same fashion that we design our print catalogs.

So, as many have discovered, we have a new way of categorizing Items, called Vocabularies and their children, Taxonomyterms. However, we must warn you that the only Vocabulary that really makes sense to dealers is the one we call “Catalog Classification”. The rest of the Vocabularies in our API are for internal use on our own websites. The reason is, we actually eat our own dog food and utilize the API to build our house brand websites. Sites like gmaxhelmetsusa.com, highway21.com, sedonatires.com, shinkotireusa.com, etc. are all built from the data retrieved from our V4 API. We’ve set up Vocabularies specifically for categorizing the pages on those sites and really shouldn't be used for any other purpose. Perhaps in the future we may even hide from dealers those Vocabularies in our API to avoid confusion.

The “Catalog Classification” Vocabulary is very top-level and overall classification to indicate which print catalog an Item belongs to, is in, or has ever appeared in. As many have also discovered, it only goes one level deep. The reason is two-fold: First, because establishing an overall categorization for over 150,000 individual Items is quite a large undertaking that we haven’t had the resources to pull off, yet. Second, we’re of the mind that doing so would be somewhat opinionated and would encourage dealers to create cookie-cutter sites that all looked the same, thereby reducing dealers ability to differentiate themselves from their competitors. We’d rather encourage dealers to construct their own structures to set themselves apart and improve the navigation of their specific website. Perhaps even giving you the top level categorization may be overstepping our role in getting you the data you need to sell products. Categorization is more of a design decision on your part and shouldn't be imposed on you by the distributor.