Getting Started with the API

This page defines various terminology and processes associated with APIs in the context of RetailNext API documentation, along with additional usage tips to help you get started.

While this page is written primarily to aid human interaction with the RetailNext API, the API is mainly intended to be used for programmed machine-to-machine interactions and human involvement should merely be once-off in order to create and test API commands.

What’s an API?

API is an acronym for Application Programming Interface. It is a set of programming code that allows software applications to communicate with each other by transmitting and exchanging data.

An API is effectively another user interface, or “window”, of a software application. Machines are generally adept at reading and using programming code within API requests and responses; while people are more adept at reading and using a graphical user interface, like the web-based RetailNext cloud interface you see and interact with through your browser. Although both forms of the interface typically interact with the same set of data, each has its own set of rules and functionality.

The RetailNext API sends and receives data in JSON format and can be interfaced with using a variety of programming languages. Our examples are documented in the context of using cURL, a command-line based tool.

API Examples

Extracting traffic data from RetailNext for integration with internal systems is one of the most common use cases of the API through the Datamine method. Below are some examples to help get you started.

Traffic Data, Store Hours

Example Request

Where the request.json file contains:

Example Response

Traffic Data, Full Day

Example Request

Where the request.json file contains:

Example Response

Traffic Data, Multiple Stores

Example Request

Where the request.json file contains:

Example Response

Traffic Data, Yesterday

Example Request

Where the request.json file contains:

Example Response

Traffic Data, Last 24 Hours

Example Request

Where the request.json file contains:

Example Response

Finding a store’s timezone

Some API methods require that you include a timezone in order to correctly resolve the date range. For example, including the store’s local timezone in v2/datamine queries when using name or relative date range specifications - such as name: now - ensures that the system knows to interpret the time now according to store local time.

You can get the timezone of a store by querying v2/locations and specifying extra fields.

In the example request below, dace69f6-b307-11e9-819d-0000698cf233 is the UUID of the store location:

The response then includes a time_zone key with an associated value. In this example, the timezone of store dace69f6-b307-11e9-819d-0000698cf233 is America/Los_Angeles.

Finding a store’s POS ID

By default, v2/location queries only include the name and UUID and some other attributes of locations.

You can get the store_id of a store; and if enabled, the store_pos_id and store_pos_division_id; by specifying extra fields in your query.

See API > Locations > Extra Fields and Filtering for more information.

Finding and setting occupancy limits

To get the occupancy limit of a store location, issue a v2/location query including an extra field of store.occupancy_limit. See API > Locations > Extra Fields and Filtering for additional instructions.

You can also set or modify the occupancy limit of a store by issuing a PUT request to v2/location/<location_uuid> that includes the intended value in the occupancy_limit parameter.

Getting video channel UUIDs and parent names

This example details how to use the location API to get a list of video channels along with the names of their respective parent locations in order to utilize the video stream API.

Location queries are made by issuing a POST to https://<subscription>.api.retailnext.net/v2/location as detailed in API > Locations. Query results have the form:

Step 1: Get stores

To get all the stores on the subscription, issue the following location query:

The response will contain a node object for each store, where the store uuid value is required for the next step.

Step 2: Get video channels for stores

To get the video channels for each store, issue a subsequent location query requesting video nodes per a store's UUID in the root_uuids field. For example, using the store shown above, the request would be:

This will return a list of all video channel nodes in the store.

Step 3: Get the names of parent locations

To get the names of the parent locations of each video channel in the store, make an additional location query requesting the parent UUIDs of each video channel in the uuids field of the request (the parent UUID is in the node object in the query result). For example:

The response will contain a node object for each of the parent nodes in the form of their name. Note that if the list of UUIDs in the query contains duplicates, the result will only contain one node object for each unique UUID.

Alternate step: One request per store

Instead of requesting the video channels and then making another query to get the information about their parents, you can combine steps 2 and 3 by requesting all the location and video nodes in one query, and then find each video channel’s parent among the returned location nodes. That query would look like this:

Applications

cURL

cURL is a handy command-line tool that can be used to test and interact with the RetailNext API and other applications.

See Using cURL for more information.

JSON Files

JSON is an acronym for JavaScript Object Notation. It’s a widely-used open standard file format for the storage and transmission of data that is structured in human-readable text. JSON files are typically characterized by key-value pairs that are organized and displayed through the use of square brackets [ ], curly brackets or braces { }, straight double quotes " ", etc.

Uploading JSON Files Using cURL

Most RetailNext API examples require the user to specify parameters in a JSON structure within a cURL command. In our documented examples, when you see -d within a command, it’s followed by a JSON file format containing the parameters and related values pertaining to the request.

Refer to the simple example below of creating a new Display location in RetailNext using the v2/location API method.

The HTTP request header: -H "Accept: application/json" informs the system that the request content-type is JSON.

Furthermore, -d "@request.json" specifies the JSON file to be referenced. In our examples, we specify @ in order to inform the system to find and upload a saved file named request.json within the root directory (default) of the user’s machine.

Instead of looking up a saved file, you could alternatively include the JSON structure directly into your cURL command. Our examples always reference a separately formatted JSON file because it’s much easier for humans to read, understand and troubleshoot.

The command below includes the JSON structure within the cURL command and achieves the same outcome as in the first example above.

Viewing and Downloading JSON Files

Responses from the API are also displayed in JSON format. When viewing responses through command-line or terminal, it may look like gobbledygook to the human eye.

Open

As with uploading JSON files from your machine, you can also specify in cURL commands that the API response is downloaded to your machine instead of being displayed through your terminal. To download the response to your root directory, append your original API request with > filename.json, where “filename” represents any name you choose for the file.

Once you have the JSON file containing the response, or by copying the response from the command-line tool, you can use a coding application like Visual Code Studio to neatly format and display the response for human consumption. You can also use a similar tool to create JSON files for API testing. Below is what the above example response looks like when formatted through a coding application.

Open

Terminology

Angle Brackets

All API examples make use of enclosed angle brackets < >. These indicate action items with some generic instruction; whereby the user must replace the enclosed instructional text with a valid string value, and simultaneously remove the angle brackets.

For example, you’ll often see "https://<subscription>.api.retailnext.net..." in the API documentation. If your RetailNext subscription name is “bayshoes” (i.e. your web-based cloud interface address is http://bayshoes.cloud.retailnext.net), your API request should look like "https://bayshoes.api.retailnext.net..."

UUID

UUID is an acronym for Universally Unique Identifier. It represents a unique identifier associated with an object in a database. In RetailNext, UUIDs are alphanumeric strings consisting of 32 characters and separated by four dashes, like 813737be-9f9d-11ea-8372-000008adea79. The term “UUID” and “ID” is used interchangeably in our documentation, although it relates to the same thing.

The API primarily references UUID values when referencing objects and, as a result, usually expects to receive and respond with the UUID of objects.

The recommended way to obtain the UUID of an object is by using various API operations, such as Inventory methods. Alternatively, or for human validation purposes, you can obtain the UUID of an object within the URL when you’ve navigated to that object in your web-based cloud interface.

In the example below, the UUID of the “Arlens Corp” region location is highlighted within the URL.

On This Page