Retail API

The RetailApi is a fully featured API that permits controlled read and write access to logical components in the retail system. This api is available public internet channels (if enabled). It supplies a restricted set of information when operating on the internet. Retailers are able to configure the retail API to grant different levels of information to different users.

The RetailAPI interface is designed with simplicity of use in mind. It is designed to be consumed by web based apps (or programs using HTTP/S transport) at a public level.

Data can be controlled. Public may never see cost price for example.
JSON default response. XML and binary formats also available
CORS support is available
RetailAPI clients connect to Fieldpine servers which provide the initial response. Fieldpine servers connect to actual retailer systems using controlled and secure methods.

Examples

GET /RetailAPI_1_2_3_4/database/products/pid/4

For retailer #1,2,3,4, return details on product with Id#4.

GET /RetailAPI_1_2_3_4/database/products

Return details on all active products. Active products are the ones typically required and exclude historic or invisible products

GET /RetailAPI_1_2_3_4/database/location/locid/21

Return details on location/store with Id#21.

RetailAPI URLs always start with the prefix /RetailAPI_N_N_N_N where N_N_N_N is the individual retailers unique 4 digit number. Number scheme 1_2_3_4 is reserved for test purposes.

Security

In order to call most RetailAPI endpoints you will need to send an API key with your request. This API key can be provided using one of the following methods

By supplying the HTTP header X-Api-Key. This is the preferred method.
By including a query parameter ?apikey= in your request

Some API endpoints can be configured to not require Api-Key and can be called by anyone freely. This is typically only used by completely public data, such as store details.

The Retail API servers provide a range of security and velocity controls for API requests and retailers are able to configure restrictions and limits for individual Api keys. Generally this will not affect you as a caller of an API. As an example of where this might be used; the call to validate a user password has the following types of restrictions

Each individual call, correct or not, is delayed for a brief period for being responded too
The rate of calls for a retailer is velocity controlled, if too many calls are received in a short space of time, the server takes remedial action
Details of the callers request are considered as well (such as geo positioning)

Retail API endpoints can generally use either HTTP or HTTPS transport, but this can be altered on a per Api key basis by each retailer.

Practical Use of Retail API

Retail API provides a controlled interface into individual retailer systems, which can be used in a variety of different ways. Some of the common options are outlined below.

WebServer calling RetailAPI

If a retailer has a public facing web server then this web server will often call RetailAPI at various times to obtain and supply information. The Api key is issued to the web server not seen by individual browsers which creates a secure environment.

A website might call retailApi to periodically obtain store details, current product information or even individual sale details. This is a very common model.

Browsers calling RetailAPI directly (login required)

If an end user is required to login to a web site before they have access, then the Api Key to use is returned as part of the login process. This method is used by many of the secure web pages Fieldpine provide on the internet.

This method is reasonably secure and the risk of Api Key leaks are reduced as Api Keys are not hardcoded into HTML and Javascript files. The downside is that each call to RetailAPI must ensure it supplies the API key, but this is easy enough if you use a common function for all requests.

When using this method, the operational flow is

User visits website and completes a login form. The browser sends username/password to RetailAPI and requests a login
If the login is successful, RetailAPI returns the Api Key to use on all subsequent Api usage. We suggest this Api key is stored in sessionStorage within the browser.
All data requests now include the provided Api Key on each request.
When the browser is closed, all trace of the Api Key vanishes.

This method results in a slightly higher number of calls to RetailApi that are billable. As the HTTP request/response includes custom header information, intermediate caches are slightly less effective if multiple users are active at the same time.

Browsers calling RetailAPI directly (NO login required)

Some API end points are returning public information and a retailer may choose to allow that API to respond without an Api Key, or at least with an Api Key that can be included in public HTML and Javascript. Where this model is being used you can simply call the RetailAPI endpoint directly from a client browser session.

This method of working is generally practical for information that is designed for shoppers directly. For example the Public Messages API returns a list of current messages from stores and is designed for customers. It typically advises current in store specials or other such information. There is no real need to protect this information, or to centralise via a retailer specific website.

Using RetailAPI in this manner typically results in the best caching performance as the requests tend to be identical across all end users. This means the response can be supplied by the Fieldpine CDN servers or internet provider proxy servers.

Apps calling RetailAPI directly

Mobile Apps can be authorised on a per App basis by granting an Api Key to that single app. This typically means the Api key is embedded into the app itself. When this is done, it is possible for advanced attackers to extract the Api Key, so caution is advised for apps with high security needs.

App designers can also broadly follow the options in either of two browser methods above depending on requirements around security and ease of use.

Trading partners calling RetailAPI

Trading partners can be authorised to use RetailAPI directly as well. In this case they will typically have an Api key issued to them, which they can use for their calls.

A typical use for a trading partner is to upload information in bulk to a retailer or poll for new information. This allows RetailAPI to be used as a replacement for traditional FTP style links.

Polling

curl -H "X-Api-Key: TRADING-PARTNERS-KEY" "https://www.fieldpine.com/RetailApi_N_N_N_N/database/open_purchase_orders"
wget --header "X-Api-Key: TRADING-PARTNERS-KEY" "https://www.fieldpine.com/RetailApi_N_N_N_N/database/open_purchase_orders"

Uploading a file

wget --header "X-Api-Key: TRADING-PARTNERS-KEY" --post-file "PriceBook.xlsx" "https://www.fieldpine.com/RetailApi_N_N_N_N/request/upload_pricebook"

Technical Internals

Api calls will return with headers to permit caching in browsers an intermediate caches as much as possible. This means that repeatedly calling the same Api may be satisfied from an intermediate cache and not Fieldpine servers. As the request was not completed by a Fieldpine server there is no charge for the response. Unfortunately browser and intermediate proxy caching is beyond RetailApis control, so requests may all be satisfied by Fieldpine servers.

If you wish to manually cache-bust a request for some reason, you can include a query string parameter of "random=???" (where ??? is a random string).

GET /RetailAPI_1_2_3_4/database/products?apikey=EXAMPLE&random=282nnd873n4e8dh5

RetailAPI will generally try and return ETag headers and obey them for requests with the "If-none-match" header present. When Etag requests are working in conjunction with HTTP caching directives you can receive changes to underlying data in responsive manner. RetailAPI has a reduced price for ETag requests that receive a "304 Not Modified" response.

If you are using Javascript in browsers, ETag and caching support is generally built in and no special action is required. If you are hardcoding requests using sockets or command line tools (curl, wget) then ETag support may not be included by default

CORS support is available for most endpoints if enabled by the retailer. CORS however is not a security restriction and should not be viewed as a way to provide security

HTTP Response Code

The following response codes can be returned for API calls

200 OK

304 Not Modified

The content you already have is still valid. This response code is typically handled by browsers themselves and not visible to Javascript.

403 Forbidden

Your request appears to be valid and correct, but the information you are requesting will not be returned. Common causes for this response include:

Your Api key is not authorised for this information you requested
Your requested endpoint is incorrect
This request was denied for velocity or security reasons

404 Not Found

The URL you requested does not exist. This code relates to the overall call itself, not the result of an API call. For example, requesting information on a non existant product will return a "200 OK" response with an empty result set, not a "404 Not Found"

408 Request Timeout

Your call was valid and proceeding but for some abnormal reason we could not complete your request in a reasonable time frame. You should retry the operation again at a later time.

Billing

This section is generic explantory information for developers. Actual prices and exact details are outlined in the RetailAPI pricing page

RetailAPI usage is charged on a pay as you go method for each API call that is resolved from a central Fieldpine server. Responses that are satisfied by browser or intermediate caches are not charged as they do not touch the central servers.

There is a variable pricing structure so that the price per API call reduces as volume increases per calender month. Pricing is based on "call rate" rather than underlying cpu, storage, network components. Having a single "price per call" is easier to understand rather than a complex method.

If you are developing against a live endpoint, there is no special free developer options. In order to keep costs down and performance up, the system is extremely simple at the billing level. The price per API call is low enough that you developing web pages using real endpoints is unlikely to incur many charges. You are able to use the Retailer Id of 1_2_3_4 for many calls without an Api Key or incurring charges. This is a test retailer for developers but has a limited set of data and reasonably restricted velocity controls. It is ideal as a starting point while you get the hang of actually making calls

A call is defined as a single HTTP verb (GET, POST, PUT etc) to an endpoint. If the request or response contains an uncompressed payload that is greater than 200Kb, then each 200Kb (or part thereof) may be counted as a request for billing purposes. Essentially, we needed to limit the case of a external user calling RetailAPI once per day and downloading extremely large responses.

API calls that use ETags and result in a "304 Not Modified" response are charged at a reduced rate. Processing of ETags still has cpu and transactional load on our servers, but generally results in very small response packets.

Internal HTTP verbs such as OPTIONS are generally either free or charged at a reduced rate if the volume becomes unreasonable

Some API endpoints are charged a premium above the normal price. These are rare exceptions and the API documentation will clearly indentify that. These APIs are those that cause much more resource usage than a typical API call. The API call that permits you to upload a photograph of an invoice can result in many internal operations: image touch-up, OCR analysis, decoding content, and finally applying to retail system.

Retailers are able to review their current charges at any time. Every API call is logged (in summary form) and available for review