Web API v2 Quickstart Guide

Bearer Token

In order to generate a token, you will need your Key and Secret credentials. Once obtained, you can generate a new token at any time using the following request body:

{
    "client_id": "{Key}",
    "client_secret": "{Secret}",
    "grant_type": "client_credentials"
}

The token will be provided in the response and is valid for all subsequent calls until expired.

A full example is available in the Examples section below.

Token Expiration

Only one token per user can be active at a time. If at any point a new token is generated, all previous tokens for that user are invalid and will not allow the client to authenticate.

Tokens expire after 1 hour. Once expired, a new token will need to be generated in order to successfully authenticate. Tokens may be generated at any time, so there is no need to wait until your current token has expired if you wish to create a new one.

Request Reference Id

Regardless of HTTP type or endpoint, every request to the API accepts an optional ReferenceId parameter. This parameter should be supplied as a GUID and is used to reference individual calls based on the client supplied value.

This is especially useful when debugging, as it allows the Hawthorne Web Team to easily identify the lifecycle of any given call and cross reference with the client's own logs.

While not required, supplying a ReferenceId is highly recommended.

Request Structure

The Hawthorne Web API uses 2 request types for REST requests, each of which have their own structure.

https://services.hawthornegc.com/v2/{path}/{endpoint}?{parameters}

{
    "ReferenceId": "GUID",
    "StringParameter": "value",
    "IntegerParameter": 1,
    "ObjectParameter": {}
}

Response Structure

Unlike requests, all responses share the same structure, regardless of HTTP request type.

Each response also includes a series of common properties alongside the call-specific data returned.

Common Properties

Each response from the API includes data specific to the request, result and performance:

{
    "Success": boolean,
    "ResponseId": guid,
    "ReferenceId": guid,
    "SuccessCount": integer,
    "Message": string,
    "ValidationResults": {
        "IsValid": boolean,
        "Errors": [
            {
                "FieldName": string,
                "FieldValue": string,
                "Allow": boolean,
                "Message": string,
                "Severity": string,
                "Category": enum
            }
        ],
        "Warnings": [
            {
                "FieldName": string,
                "FieldValue": string,
                "Allow": boolean,
                "Message": string,
                "Severity": string,
                "Category": enum
            }
        ],
        "Info": [
            {
                "FieldName": string,
                "FieldValue": string,
                "Allow": boolean,
                "Message": string,
                "Severity": string,
                "Category": enum
            }
        ]
    },
    "QueryTime": string
}

For more details, please see our full documentation here. The response examples can be found under the "Responses" section of each call.

Request Specific Data

In addition to the common properties above, each response also includes data relevant to the specific request that was made. This data can be found nested under the "Data" object in the response.

{
    "Data": {
        ...
    }
}

For more details, please see our full documentation here. The response examples can be found under the "Responses" section of each call. Clicking on the "Data" property in the object tree will show the properties specific to each request.

Documentation

• Hawthorne Web API Documentation
• How to Use REST APIs
• OAuth 2.0

Third Party Applications

• Postman API Tools
• JSON Formatter

Postman Collection

To get started using Postman, you can download the collection of web API calls from here.

.NET (RestSharp)

public class TokenResponse
{
    public string access_token { get; set; }
    public string token_type { get; set; }
    public int expires_in { get; set; }
}
                            
public string GenerateToken()
{
    var client = new RestClient("https://services.hawthornegc.com/v2/token");
    var request = new RestRequest();

    request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
    request.AddParameter("client_id", "{APIKey}");
    request.AddParameter("client_secret", "{APISecret}");
    request.AddParameter("grant_type", "client_credentials");
    var response = client.Post(request);
    var result = JsonSerializer.Deserialize(response.Content, new JsonSerializerOptions
    {
        PropertyNameCaseInsensitive = true
    });

    return result.access_token;
}

public string GetPartDetails()
{
    //Generate a new token - Only do this if you haven't generated one yet, or the previous token used is expired
    var token = GenerateToken();
                                
    var client = new RestClient("https://services.hawthornegc.com/v2/Part/Details");
    client.Authenticator = new OAuth2AuthorizationRequestHeaderAuthenticator(token, "Bearer");

    var request = new RestRequest();
    request.AddParameter("PartId", "HGC749300");
    request.AddParameter("PartType", "Standard");
    request.AddParameter("DealerPricing", true);
    request.AddParameter("AllWarehouses", true);
    request.AddParameter("IncludeUnavailable", false);
    var response = client.Get(request);

    return JsonSerializer.Serialize(response.Content);
}

PHP (cURL)

function GenerateToken() {
    $tokenCurl = curl_init();

    curl_setopt_array($tokenCurl, array(
        CURLOPT_URL => 'https://services.hawthornegc.com/v2/token',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => '',
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => 'GET',
        CURLOPT_POSTFIELDS => 'client_id={APIKey}&client_secret={APISecret}&grant_type=client_credentials',
        CURLOPT_HTTPHEADER => array(
        'Content-Type: application/x-www-form-urlencoded'
        )
    ));

    $tokenResponse = curl_exec($tokenCurl);

    curl_close($tokenCurl);
    return $tokenResponse.access_token;
}

$token = GenerateToken();

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://services.hawthornegc.com/v2/Part/Details?PartId=HGC749300&PartType=Standard&DealerPricing=true&AllWarehouses=true&IncludeUnavailable=false',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => array('Authorization: Bearer ' . $token)
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python (http.client)

import http.client

def generate_token():
	tokenConn = http.client.HTTPSConnection("services.hawthornegc.com")
	payload = 'client_id={APIKey}&client_secret={APISecret}&grant_type=client_credentials'
	headers = {
        'Content-Type': 'application/x-www-form-urlencoded'
	}
	conn.request("GET", "/v2/token", payload, headers)
	res = conn.getresponse()
	data = res.read()
	return data

conn = http.client.HTTPSConnection("services.hawthornegc.com")
token = generate_token()
headers = {
    'Authorization': 'Bearer ' + token
}
conn.request("GET", "/v2/Part/Details?PartId=HGC749300&PartType=Standard&DealerPricing=true&AllWarehouses=true&IncludeUnavailable=false", '', headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Other

For any languages not listed here, Postman offers functionality to convert a call into the given framework. Further documentation on that can be found here.