About the Fieldpine OpenApi interface

Base Paths

Each retailer using Fieldpine is allocated a unique 4 digit number called their 'RmSystem'. If you are calling OpenApi to a Fieldpine server you will need to change your base path to include this number.

For example, the normal BasePath might be

/OpenApi2/Validate/Email

however the same call made to Fieldpine.com would be

/OpenApi2_3,4,5,672/Validate/Email

You can include the RmSystem value in all requests if you wish.

The OpenAPI is case insensitive for API requests, including both paths and query parameters. Response formats are always returned using the same casing. Exceptions to this will be clearly documented within the individual API.

API versioning is controlled using the BasePath. /OpenApi2_xyz means the request is using Version 2 of the API definition.

HTTP Verbs

GET Responses confirm to current OpenAPI requirements.

DELETE Responses confirm to current OpenAPI requirements, however, not all functions have delete calls as this is a "system of record" and information cannot be destroyed (GDPR aside). Some DELETE operations are internally "hide from user view unless absolutely required", however eLink takes care of this implementation detail

POST A POST operation to us is an Insert or an Edit, aka upsert

• If you provide the ID key for the record and it exists, it will be editted.
• If you provide the ID key and it does not exist we will attempt to insert a new record with that value.
• If you do not provide an ID key, we treat this as an insert and generate a new ID key value

The eLink API, which OpenAPI uses internally, provides idempotent versions of POST already, so if you send EXACTLY the same information multiple times, we will only do it once. This can make your retry logic very simple - just send it multiple times - as we will de-duplicate requests.

PUT Internally, we convert these to POST/upsert operations. There are not many PUT functions defined in the documentation as it would simply clutter the documentation. The big advantage of PUT for other applications is that it is idempotent, however our POST calls offer this as well. You may send PUT requests instead of POST if you wish, the structure is identical.

A PUT request that does not include values for fields, will not change those fields. You must explicitly zero fields. Primarily this is because the version of the record you GET might be a subset of fields in the complete record.

PATCH Implemented rarely

Rate Limiting

If you are NOT calling a Fieldpine.com server then rate limits are typically not applied. In these cases you are communicating to a retailers private server and there is little reason to rate limit. There are some exceptions around operations such as login failure, prepay cards and other more secure APIs.

If you ARE calling a Fieldpine.com server then rate limits will generally by applied.

API Pricing

The API definitions include pricing details. For the vast majority of APIs this is 'standard' which means the API is included in the pricing bundle used by the retailer. Some APIs will say 'premium' or another term - this implies that particular API has additional charging. For most development you are likely to only use standard pricing APIs. A small number of APIs are marked 'free', typically those providing directory type services to allow you to dynamically locate server endpoints.

An example of a premium API is a the set of APIs that allow you to upload photographs and scans and have Fieldpine automatically decode and process them, as if they had been keyed in. The actions performed by this API can involve a lot of backend processing, including the use of sub contractor APIs that are charged to Fieldpine

Premium APIs are generally automatically rate limited to very small defaults, and retailers must explicitly enable higher volumes - this is to stop unexpected billing charges.

What is the pricing? For exact pricing please refer to Fieldpine Pricing, but in general terms:

Using in house API Servers

Generally free and not rate limited, except for Premium APIs which remain chargeable. See Fieldpine Architecture for what is an 'in house' server

Using Fieldpine.com Servers

API calls are charged using an 'Access Minute' method where the first API call opens a window of 60 seconds on the server for that client. The client can make any number of calls within that 60 second window. There are some limits around maximum bandwidth within the window as well. This approach means that when an app requiring calls becomes active it can make numerous calls without being overly concerned about charging. For example, the Fieldpine Excel addin can call hundreds of APIs per second while a spreadsheet is being recalculated - this becomes a single 'Access Minute' for charging.

API responses are typically marked for client browser and CDN caching; as cached requests do not get resolved by fieldpine.com servers every time, they do not trigger an access minute. So calls for slow moving data such as a list of stores or product departments will often be resolved from the CDN and only incur charges infrequently when the cache invalidates.

High volume retailers can deploy their own internet facing server using their own (or cloud hosted) servers to avoid Access Minute charging and pay a fixed Monthly fee.

Browser Caching

Many API requests are marked with cache instruction headers for the browser. In order to achieve performance these cache instructions often grant the browser a version of a record that does not expire for several minutes. This dramatically reduces network load and cost savings in some environments. This means that for some sequences of requests you may see stale data, if you change reference style data such as product definitons, stores and so on.

1. GET /OpenApi2/Staff/123
   This is a typical request to retrieve information. The server may respond with caching instructions informing the browser it can satisfy future requests without touching the server. This may also involve a CDN cache, even if not cached in the browser. This is great for performance as this sort of data is typically infrequently changed.
2. POST /OpenApi2/Staff/123
   This a a typical request issued to update a record. No problems here, this bypasses all caches and goes directly to the server
3. GET /OpenApi2/Staff/123
   If you request data again, perhaps to verify the change occurred, then potentially the browser or CDN may return a cached copy. There are a few options to workaround this
   • When issing the GET request, add the HTTP header "Cache-Control: no-cache". This instructs the browser and CDN proxies to ignore any cached value and request the resource from the origin. How you add this header depends on the toolset you are using.
   • Include the query parameter ?99=random-string on the request URL. The "99" query parameters is universally understood by Fieldpine Applications to be a random value and is ignored. The presence of a unique query parameter means the request will not match any existing cache entry and will be passed to the origin

Addtional Information. API endpoints can and will return the complete range of caching mechanisms, such as private/public, browser and CDN caching, ETags and conditional requests.

CDNs and Caching

The resposnes to most API calls are marked as 'private' for obvious reasons. This, and the inclusion of an x-api-key in the header, typically means that your request will be proceessed by an origin server and not satisfied by a CDN cache. For performance reasons it would be better if your request was answered from the CDN cache.

As a developer you do not need to use the token-url scheme described below unless one of the following apply:

• Your application will make requests that are the same from different instances of your application. ie Those were getting a CDN response would be benefical
• You are trying to avoid the delay introduced by CORs preflights
• The retailer has asked you too, typically because it might reduce their usage charges
• You require the absolute maximum performance.

If enabled by the retailer (and the default is Off) selected API results can be moved to a complex URL and marked public. This means you can call the API and receive information from a CDN cache if available. When using this method, you can change the base path to include the token

From
/OpenApi2_3,4,5,672/Validate/Email

To
/OpenApi2_3,4,5,672$token/Validate/Email

The token is not your API-Key, it is a dynamically changing opaque value. Broadly speaking tokens are replaced every day. When making a request using this token method you should not include your API-Key as this may stop the CDN from serving from cache. Not sending the x-api-key also means that any CORS requests may not need to pre-flight

Several types of requests are now possible:

1. If you make normal request to /OpenApi2_3,4,5,672/Validate/Email and include your X-api-key the server may respond with
   • A 2xx response with data in the payload and the response marked private. This is served by the origin.
   • A 302 response to a token url and responses marked public. The 302 is served by the origin and the following content is hopefully resolved from the CDN. As this involves 2 network trips it doesn't offer your client application any benefit but does have some minor origin benefit. This type of response is infrequent, although might be seen more commonly for items such as photos and documents
   • In rare cases you may receive a 2xx response with the response marked public. This is where the response can be safely cached and served even if the request had not specified an x-api-key. This is used by request/responses of totally public data.
2. If you make a request to /OpenApi2_3,4,5,672$token/Validate/Email and do not include your x-api-key:
   • If the response is held by the CDN, the CDN will return it. This results in the fastest client response and also reduces the retailers usage charges as responses from CDNs are not charged by Fieldpine.
   • If the response goes to the origin server, the response will be returned and marked public so the next caller can be resolved from the CDN. If the retailer has not enabled the use of public token url for the request, you will receive an HTTP error
   • In some cases the origin server may also respond with a 302 redirect to a previous token-based url. Again, this is infrequent.
3. If you make a request to /OpenApi2_3,4,5,672$token/Validate/Email and do accidentally include your x-api-key, it will be treated the same as case #1 above.

Retailers have options to control the level of token-url caching. The default value is to allow any client level encrypted payloads (for applications that have client side keys - it does not mean delivered over SSL) and also to allow any 'low risk' data.

Tokens themselves are opaque values consisting of characters from the safe url path characters. They change frequently and randomly vary in length as well.

To get the current token, make an request to the AboutMe function, if enabled and you are authorised to use it, a UrlToken value will be returned.

Response Content Type

Almost all API calls will respond with:

• Application/JSON - For structures in JSON format
• Application/XML - For an XML representation

Many bulk style API calls will also respond with the following types. Actually most API calls can respond with these formats even if not listed:

• Application/vnd.ms-excel - Excel spreadsheet

Some API calls have additional response types you may not be familiar with:

• application/vnd.fieldpine.gnap The native binary format used by GNAP. This is tightly packed binary format designed for bulk transfers. While not documented, it can be if required for valid use cases. Fieldpine applications typically use GNAP format as it has lower latency.
• application/vnd.fieldpine.tenglish This is an english like syntax designed for passing to and from 3rd parties. It is designed to be expressive, forgiving and also human readable. It has minimal structural syntax requirements, such as needing quotes or brackets in the right place. We do not suggest using tenglish except for some specific interchange situations.