REST API End Point URL

Overview

One of the most difficult things when first working with any REST API is trying to figure out where the URL is that allows you to get or post information to the application.  Hotcakes makes this easy for you with this article and the sample REST API project.

Requirements

The following pre-requisites will be necessary to accomplish the goals of this article:

• General understanding of REST and API’s
• General understanding of C# and/or JavaScript (jQuery)

Getting Started

The only thing you need to know before you get started is that you should already have a CMS site up and running with Hotcakes Commerce already installed with an API key ready for you.  That is, before you start writing code.  This article might be the final step before you actually get some code written.

REST API End Point URL

The API end point you’ll be using can be broken down into 5 parts.  Consider the following example URL that allows you to get a listing of the categories.

http://yourdomain.com/DesktopModules/Hotcakes/API/rest/v1/categories

Section	Description
http://	This value can be either http or the SSL equivalent of https, depending on your project requirements and server configuration.
yourdomain.com	This value should be the domain name that you’re developing against or the production website domain name.
/DesktopModules/Hotcakes/API/rest/	This is the path where your API can be found. This should be the same regardless to the Hotcakes API version.
v1/	This is the version number of the API. This value will be “v1” for all API calls until a new version of the API is released.
categories	This is simply the end point that you wish to call to either post information to the API or get information from the API. This value can be any number of other end point names as well as “categories” in this example.

The only time you will need to manually build the URL for calls to the REST API is if you perform calls using JavaScript.  If you are using C#, the URL will be built for you.  All you will need in that scenario is the API key, domain name, and end point.  The code will always call the right API end point URL for you.

Parameters

Every end point will have varying requirements on the parameters it expects.  However, all end points will require at minimum a key.  This means that you need to create an API key in your store and then include it on every API call.  An example of the key being included on the URL is seen below.

http://yourdomain.com/DesktopModules/Hotcakes/API/rest/v1/categories?key=1-b91c45bc-1752-4fb9-aa48-f59b68244b57

HTTP Methods

Be sure to pay attention in the documentation on which HTTP method to use when asking for a specific action to be executed in the REST API.  We make use of most of them.  It's not just GET and POST.

Return Values

The REST API uses JSON exclusively.  All data you submit and retrieve will be in JSON format.  In all cases, you should have objects for Errors and Content.  Errors will contain any errors that have occurred.  If no errors occurred, you should have an empty collection like shown below.  Content will contain any return values that you requested in your API call.  This could be something as simple as a true/false or as complicated as a listing of products in the store.

{
	"Errors":[],
	"Content":[]
}