Api.heavytruckparts.net

From ISoft Wiki
Revision as of 12:47, 16 April 2018 by Broy (talk | contribs) (→‎Making a Request: Added an example for only keywords)
Jump to navigationJump to search

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/inventory/search/<part type>/<make or manufacturer>/<model>?<filter options>

The request should be URI escaped: 

https://api.heavytruckparts.net/inventory/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. The keyword search looks for ALL keywords, but can be structured via pipe (|) operators for OR behavior. For example, keywords=(first set of search terms)|(second set of search terms)
    • category: an item category to limit the results by. This is usually something like "NEW", "USED", or "CORE", but a full availability list for Categories can be requested (see Availability Lists below)
    • 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.
    • result_size: the number of results to be returned "per page." This value can be an integer count of results (the default is 25) or the word "all." Please note that specifying "all" or a large number can result in very poor search performance. Additionally, depending on the user configuration, the search may have specific requirements before this parameter takes effect: For non-vendor specific searches and/or large values of result_size, the API may require a part type, make, model, and enduserid to be specified. "Body" or "Vehicle" parts may require a year or year range to specified. If these values are not specified in the search, the API may ignore the result_size parameter and present the default 25 result page size. Please contact ISoft Data Systems if you have questions regarding result_size support and strict search requirements for page sizing for your specific API user requests.
    • 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", "vendor", and "date_added".
    • 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").
    • show_suggested: an optional parameter which can be set to "1" or "true" to show suggested part types for a search. This only produces results for searches which do not have a part type set. This requests the API include links to more specific searches in the current search to "drill down" the search results. This may be turned on for an apiuser to affect all of their valid searches (without needing to be specified in the query string for the searches).

The exact search format can be customized for individual API users. In general, the search parts are "optional" but require a place holder (though in most cases, if some search parts are not used, a keyword search filter is encouraged to help narrow down search results). Due to the nature of URLs, something must be entered for each search component to form a valid URL. In a standard search URI, providing the "magic" character asterisk (*) for a search component will cause that search component to be ignored for the purposes of the search. For example, 

https://api.heavytruckparts.net/inventory/search/*/FULLER/*?keywords=warranty

To perform a keyword-only search, you can leave the part type, manufacturer, and model as all "wildcards" and just specify a keyword filter: 

https://api.heavytruckparts.net/inventory/search/*/*/*?keywords=warranty

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 by default; if no specific result "page" size is requested. 

{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",
   email:"the vendor's email address"},
  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"]
}

If show_suggested is set, the results include an additional suggested_part_types object: 

{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",
   email:"the vendor's email address"},
  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"],
  suggested_part_types: [ 
    { part_name: "the part type name", 
    part_type_id: "the part type id value for this part type",
    uri: "the full URI for a search based on this part type but otherwise identical to the current search"
    } ]
}

Other Requests

The API handles more than just searches. You can request details on particular inventory items or fetch the available part types, manufacturers, or models for your API user.

Item Details

An item details request provides more information on a particular item than the basic search result provides. 

https://api.heavytruckparts.net/inventory/details/<vendor code>/<vendor store>/<inventory item id>?[userid=<end-user id>

The information is provided in JSON form, just like the search results, and includes all of the important data from the search results entry as well as further information on that specific inventory item. There are "Q&A" options which are vendor specified label: value pairs. The exact data in these fields and how many there are cannot be predicted, as they are specified by the item vendor. The optional userid request option is used for determining custom pricing and availability when applicable. 

{part_name: 'part type name',
 vendor_part_name: 'vendor-specific short part type description',
 year: 'year of item manufacture or production, if available',
 vehicle_make: 'make of vehicle for item, if available',
 vehicle_model: 'model of vehicle for item, if available',
 part_manufacturer: 'manufacturer of item, if available',
 part_model: 'part model of item, if available',
 oem_number: 'OEM number assigned to item',
 serial_number: 'Serial number assigned to item, if available',
 vendor_sku: 'Vendor SKU or Tag Number',
 vendor_vehicle_id: 'Vendor's ID for the Vehicle or Whole Unit for the item, if available',
 vin: 'VIN, if available',
 core_price: 'core return price',
 price: 'item price',
 description: 'item description with all HTML tags stripped',
 html_description: 'item description with HTML tags intact',
 condition: 'vendor specified item condition',
 category: 'item category, i.e. USED, NEW, REMANUFACTURED',
 available_quantity: 'available quantity of item',
 side: 'side of vehicle item fits, if available and appropriate',
 'vendor_specified_option_label, for instance "HP" or "Color"': 'vendor_specified_option_value'
 ...
 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",
   email:"the vendor's email address" },
 images:["an array of URLs for images associated with this item"]
}

Available Lists

Requests can be made to the API to fetch the complete list of part types, make/manufacturers, models, and categories for your API user. These results are customized to match your API user's mapping data (so the results can be used directly to produce search request URIs) and by default are limited to include just those part types, makes, manufacturers, models, and part categories that pertain to the result set returned to your API user in searches (the lists will not include part types that you wouldn't find in your search, for instance). The query string filters for specifying part types for available make/manufacturers, models, and categories; and make/manufacturers for available models are optional. That said, it is strongly encouraged to specify a part type for category availability if vehicles or whole units may be included in all your possible search results, because the category field has a different contextual meaning between a whole unit and a component part.

You may optionally pass the query string parameter of "all_results=true" if you want to include all of HeavyTruckParts.Net's possible choices, even if those options would not be found in your search results. You may optionally pass the query string parameter of "ignore_mapping=true" if you want to have the API ignore your possible mappings and return HTP's native results, rather providing you with the mapped value that matches your data. 

https://api.heavytruckparts.net/inventory/available/part_types
https://api.heavytruckparts.net/inventory/available/makes?part_type=<part type to filter make/manufacturers by>
https://api.heavytruckparts.net/inventory/available/models?part_type=<part type to filter models by>&make=<make/manufacturer to filter models by>
https://api.heavytruckparts.net/inventory/available/categories?part_type<part type to filter categories by>

The results are, as before, specified in JSON format. 

[
 {part_types_id: 'part type id value', part_type_name: 'part type name'}
]

[ 
 {make: 'make or manufacturer name'}
]

[
 {model: 'model name'}
]

[
 {category: 'category name'}
]

Parts From the Same Vehicle

After requesting details on a particular item, it may be useful to find what other items are available which were taken off of the same whole unit or vehicle. This can be done by placing a "wholeunitparts" request with the appropriate vehicle id: 

https://api.heavytruckparts.net/inventory/wholeunitparts/<vendor code>/<vendor store>/<vendor vehicle id>?[userid=<end-user id>

The results are in JSON format, and are a relatively simple listing of all the items which are marked as coming from that same whole unit, along with detail URIs for those items. [ 

{ part_name: 'part type name',
 vendor_part_name: 'vendor-specific short part type description',
 make_model: 'the make or manufacturer and model of the item',
 vendor_sku: 'Vendor SKU or Tag Number',
 details_uri: 'a URL to request for further information on this item',
 price: 'the retail price of the item, or a custom price for the end user, if available' }

]

End-User Templates

End user custom results processing (availability, quantity, and pricing) are defined by templates, created in partnership between the API user and ISoft Data Systems. These templates are given names for ease of reference. A GET request to enduser/templates will provide the template list (a template type may optionally be provided to limit the templates received, otherwise all template types will be returned). A PUT or POST request can be used to assign a template to an enduser by their enduserid. A HEAD request will provide all the available template types. A DELETE request will remove the associations between an end-user and a template, effectively reverting that user to the default behavior for that template type. 

HEAD https://api.heavytruckparts.net/enduser/templates : Provides the template type list.
https://api.heavytruckparts.net/enduser/templates[/<optional template type]
https://api.heavytruckparts.net/enduser/templates  : Returns the list of all templates which can be assigned to an end user
https://api.heavytruckparts.net/enduser/templates/pricing : Returns the list of all pricing templates which can be assigned to an end user.

The results are returned in JSON format, specifying the template name and the type of template: 

[{template_name: "template name", 
 template_type: "template type"},
...
]

When assigning a template, you can use the pseudo-type "all" to use the same template name for all template types: 

POST https://api.heavytruckparts.net/enduser/templates/<template type>?userid=<end user id>&template=<name of template to apply to end user>
POST https://api.heavytruckparts.net/enduser/templates/all?userid=1&template=Dealer : Would assign the "Dealer" template for all template types to the end user 1

The "all" pseudo-type also works for removing template associations: 

DELETE https://api.heavytruckparts.net/enduser/templates/<template type>?userid=<end user id>
DELETE https://api.heavytruckparts.net/enduser/templates/all?userid=1

End-User Lookups

If you are trying to introspect customerids from an attached ITrack System, the API may be configured to return the id value for a given email address. The resulting value is suitable for use as the "userid" or enduser id value that you pass to the API for customer-specific pricing and availability. 

https://api.heavytruckparts.net/enduser/lookup?email=<email address>

If you know the end user id, it can be passed in to look up information about that customer as well. 

https://api.heavytruckparts.ent/enduser/lookup?userid=<end user id>

The results are in JSON format. The GET method will return most of the customer data, the HEAD method will return just the customer id. 

{userid: "customer id / end user id",
 company: "the name of the customer's company",
 name: "the customer's name",
 street: "the customer's street address",
 city: "the customer's city",
 state: "the state or province for the customer",
 zip: "the zip or postal code for the customer",
 country: "the full country name for the customer",
 country_code: "the two-letter country code for the customer's country",
 email: "the customer's email address",
 phone: "the customer's phone number"
 }

If you need a list of all enduserids that the system has associated with a template, the API can be configured to provide that information. 

https://api.heavytruckparts.net/enduser/listall

The results are in JSON format, and contain an array of objects listing the end user and their current template association. 

[{userid: "customer id / end user id",
 company: "the customer's company name",
 name: "the customer's name",
 email: "the customer's email address",
 templatename: "the name of the template associated with this customer"

}]

It may be possible for ISoft to configure the API to automatically generate template associations for you. In this case, you may request that the API refresh the template associations (which generates associations for new users and corrects the associations for existing users) when making a list request: 

https://api.heavytruckparts.net/enduser/listall?refresh_list=true

Mapped Types

If you have a deep part type mapping (you primarily interact with the API using an abstraction which replaces HeavyTruckParts.Net part types and has its own mapping to those types maintained in ITrack -- this is the Part List Authority in ITrack, and is used to represent concepts like "Function Groups" -- you may want to know what HeavyTruckParts.Net may be included in any particular custom mapped part. This list can be requested via 

https://api.heavytruckparts.net/inventory/mappingtypes/<mapped type>

The results are in JSON format, and contain an array of objects listing the HeavyTruckParts.Net "part type" numbers and the human-readable type name that correspond to the mapped type, or would be included in searches against the mapped type, if any exist. 

[{
  part_type: "HeavyTruckParts.Net part type id", 
  part_name: "The name of the HeavyTruckParts.Net part type"
}]

Mapped types may be represented a hierarchical fashion. These hierarchies can be filtered by category. Each call to the "functiongroup" request will return a particular level of a hierarchy, optionally filtered by category. By providing a "parent" as part of the query string, you can get deeper levels of the hierarchy. 

https://api.heavytruckparts.net/inventory/functiongroup?[category=<filter category>][&][parent=<parent function group id>]

The results are in JSON format, and contain an array of objects representing the mapped types at this level in the hierarchy. This includes the function group id, and the function group name. By providing a function group id as the parent to a subsequent request, you can retrieve the mapped types that have that mapped type id as their "parent" type. 

[{
 function_group_id: "mapped type id",
 function_grup_name: "The name of the mapped type"
}]

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.
  • The API tends to use the word "make" in the requests, responses, and documentation, but except for places like the item details where vehicle_make and part_manufacturer are explicitly separated, it considers make and manufacturer (as well as vehicle model and part model) interchangeably. If you check availability for "makes" for, say, engines, which are based on part manufacturer rather than vehicle make, then the engine manufacturers will be returned in the list, not the vehicle makes of the vehicles the engines came out of.
Retrieved from "https://wikido.isoftdata.com//index.php?title=Api.heavytruckparts.net&oldid=10366"