Api.heavytruckparts.net

API access can be provided to the HeavyTruckParts.Net data store. The API can be a convenient way to provide access to search results or to a customer's inventory on HTP.Net.

RESTful Service

The API is a RESTful service. That means that requests to it work just like making a request to a website. You use a URL, with a possible query string to add filters to the behavior, with an HTTP method (usually GET) and the results are returned to you. Another thing to keep in mind that, as a pure RESTful service, there is NO STATE in the API. It does not have sessions, and doesn't remember anything about a request. That means that a user MUST provide authentication details with EVERY request made.

Authentication and Security

The API authenticates with a user and password (which will be pre-agreed on between ISoft and any client who wants API access) via HTTP Basic authentication. Basic authentication is not, in and of itself, secure. So to combine the ease of Basic authentication with additional security, the API requires access over HTTPS. Industry standard SSL-encryption protects every API request, so Basic authentication can be safely used.

Customized For Each API User

The API results are customized on the basis of the API user that authenticates with the API. So simply by presenting the correct user, the API will automatically determine which dataset to provide (automotive, motorcycle, yellow iron, or heavy truck). It also determines the customization for the user. The API user provides their own part types, manufacturer, and model information in a search. This information is used by the API to map to the values used by HeavyTruckParts.Net. Additionally, search results are customized by the API user, so an API user can have access to a predetermined set of vendors' inventory, with customizable default filters. An API user can be defined to prefer data in XML or JSON format; by default the API provides JSON-formatted data back to the API user.

Customized For End Users

The API can accept an id for the end user -- that is, the person visiting the website of the API User or using the webapp built by the API user. Customizations-per-end-user that can be applied include custom pricing (if the id can be matched to the appropriate customerid in a vendor system), default distance sorting (if the id can be matched to a particular zip code), or special availability rules.

Making a Request

So how is a request made? Assuming that you have a valid API User and know how to make the request, providing that user and password via Basic authentication, API requests are just HTTP GET requests:

https://api.heavytruckparts.net/search/<part type>/<make or manufacturer>/<model>?<filter options>

The request should be URI escaped:

https://api.heavytruckparts.net/search/Engine%20Assembly/CUMMINS/ISX?year_range=2013,2015&zipcode=68503&distance=100

• Part Type: The part type is specified on the URL as the first part. This may be a string or numeric value; it will be mapped to the appropriate value for HTP.Net based on your API user. This is a many-to-many mapping: You may have a part type that maps to many HTP.Net part types, or many part types that map to a single HTP.Net part type.
• Make or Manufacturer: The vehicle make or part manufacturer for the part search, specified on the URL as the second part. This is a many-to-many mapping: You may have a manufacturer that maps to many HTP.Net manufacturers or many manufacturers that map to a single HTP.Net manufacturer.
• Model: The vehicle or part model for the part search, specified on the URL as the third part. This is many-to-many mapping: You may have a model that maps to many HTP.Net models or many models that map to a single HTP.Net model.
• Filter Options: An optional query string of <filter>=<value> options, separated by & symbols to add as many filter options as desired.
  • year_range: a comma separated value of "first_year,last_year" inclusive. A 0 means "all years." "year_range=0,2003" is "all years up to and including 2003.
  • zipcode: the zipcode to distance search from. By default, if a zipcode is provided, results will be sorted by distance.
  • distance: a distance in miles to limit results to. Requires zipcode to be specified, 0 means "any distance."
  • keywords: a space-separated list of keywords to perform a keyword search with.
  • userid: the end-user id, representing a person using the website or webapp which relies on the API. Pricing and other values in the results can be customized based on this value.
  • page_number: the results are separated into separate "pages" results. This value indicates which "page" in the results should be returned.
  • sort_column: the column in the results that the results should be sorted by. The default is "price," unless a zip code is specified, and then the default is "distance." Allowable values are "part_name", "make_model", "year", "oem_number", "vendor_sku", "description", "price", "coreprice", "condition", "type", "distance", and "vendor".
  • sort_order: the "direction" the sort_column should be sorted on. The default is "ascending". Allowable values are "ascending" and "descending" (or the abbreviations "asc" and "desc").

Results

Results are provided, by default, in JSON format, though XML results could be provided instead. Results are "paginated" or broken into "pages", just like a Google search. 25 results are provided to a page.

{results:
 total_results: the total number of results for this search,
 total_pages: the total number of search result "pages" in this search,
 [type:"(USED,NEW,REMANUFACTURED, etc...)", 
  vendor:{
   company:"company name", 
   contact:"contact person", 
   city:"city the vendor is in", 
   state:"state the vendor is in", 
   postal_code:"zip code or postal code for the vendor",
   phone_number:"the vendor's phone number", 
   fax_number:"the vendor's fax number" },
  part_name:"the part type name",
  make_model:"the make or manufacturer and model of the item",
  year:"the year of the item, if provided",
  oem_number:"any OEM number associated with the item",
  vendor_sku:"the SKU or Tag Number assigned to this item by the vendor",
  description:"the description of the item",
  price:"the retail price of the item, or a custom price for the end user, if available",
  coreprice:"the core return price on the item, if any",
  condition:"the item's condition, as described by the vendor",
  details_uri:"a URL to request for further information on this item",
  images:["an array of URLs for images associated with this item"],
  distance:"the distance of the item, in miles, from a provided zipcode",
  page_number:"the page number this item is found on"]
}

Things to Remember

• The API is stateless. If you have a request for a particular end user (like custom pricing) it is your responsibility to provide that end user id, and to ensure that the correct end user id is passed in any request for that end user. If you are handling sessions for your users, session management is your responsibility; the API has no concept of sessions.