Changes to root API endpoint and response payloads

Publish Date: 2016-01-19

API Root Endpoint Change

There is a new endpoint that should be used going forward for all API requests. Previously, requests were sent to "/TMA/v1/XXXX", but now they should be sent to "/api/v1/XXXX". The "/TMA/v1" endpoint will still work but it will be missing many of the recent updates to the API. We expect to turn off access to this endpoint on Friday Jan 22, 2016. You do NOT need a new subscription to access the "/api/v1" endpoint.

Details of the supported operations can be found here.

Changing "Sparse" flag to "Verbose"

Many of the API requests, especially endpoints that return a List of data, return a subset of available object data by default. By passing an optional GET parameter you can request that full objects are returned. In general, the default response is enough to generate a user interface but there may be cases where more information is needed.

To get full object details (where supported) pass a GET parameter with a key of "verbose" and a value of "true". Previously, you had to pass a key of "sparse" and a value of "false" to utilize this behavior. The "sparse" flag is no longer supported.

Be aware that setting the Verbose flag to "true" will cause the response to be much slower. Use this feature only where appropriate.

Changing "SystemKey" to "ID" in Order

In the "Order" collection of endpoints, the request and response payloads previously contained a property named "SystemKey". This value represents the system ID of the order request; it is used in subsequent API requests to identify the Order.

This property has been updated from "SystemKey" to "ID". No other behavior has changed.

Changing "EchoKey" to "PartnerOrderReference" in Order

In the "Order" creation endpoint, the request and response payloads previously contained a property named "EchoKey". This property was intended to be a transient developer-specified identifier used to match batch items with resulting objects in the response.

The functionality and property name has changed and needs to be updated accordingly. Now instead of passing an "EchoKey", the developer may optionally specify a "PartnerOrderReference" value. This value may be unique (encouraged) or not. This user-specified value is now persisted to the Order. Functionality is being added to the API to allow for searches using the "PartnerOrderReference" field.

Meta endpoints now available

A new collection of endpoints have been added to provide information about the different lookup types/enums used by the PFLlink API.

These endpoints are:

Changing "Shipping" to "Delivery"

Throughout the API, any properties or paths that contained "Shipping" have been updated to instead use the term "Delivery". This change affects the /order endpoints.

Additional meta information now available in API responses

On all 200 level responses, a new property has been added to provide extra information about the request and response. This property is named _meta; it is an object that contains additional information useful to the developer. As a convention, any property on an object that starts with an "_" (underscore) character is private and should not be shown directly to an end user. For now, only the "_meta" property is available but others could be added in the future.

Demo store behavior

The Demo Store is no longer automatically associated with new Users or Applications. A developer must now explicitly add the Demo Store by making a call to the /store/invite endpoint (for Users) or by using the /application/{applicationID}/store endpoint (for Applications).

For Users, an Invite Key of "demo" should be used.

For Applications, the User making the request must have access to the Demo Store before it can be added as an explicit Application permission using the /application/{applicationID}/store endpoint.

Order ID and Order Number use for identifying an Order

Any Order request will have two values that may be used for identifying an Order in the PFLlink API. The Order ID (formerly System Key) represents the Order Request and is available as soon as a request is submitted to the /store/{storeID}/order endpoint. This Order ID will take the form of a GUID. It can be used with the /store/{storeID}/order/{orderID} endpoint to get Order details or the /store/{storeID}/order/{orderID}/status endpoint to get Order status.

Additionally, a Order Number value will be available once the Order Request has been processed by the back-end systems. This Order Number is available from the /store/{storeID}/order/{orderID} endpoint. The Order Number can be used in lieu of the Order ID (in the URL) when making requests to the /store/{storeID}/order/{orderID} or /store/{storeID}/order/{orderID}/status endpoints

Changing Estimate endpoint name to Price

The /store/{storeID}/order/estimate has been updated to a new endpoint. Please use /store/{storeID}/order/price. The payload and response have not changed.

Removal of UsernameWithDomain on /user endpoint response

The /user endpoint no longer contains a UsernameWithDomain property on the response object. Now, this value is available under the "Username" property.

Previously the response contained both the Username and UsernameWithDomain properties. As an example, the "Username" would be represented as Malcolm.Reynolds while "UsernameWithDomain" would be represented as Malcolm.Reynolds@appcenterpfllink.onmicrosoft.com. Now the response only contains a "Username" property with the value represented as Malcolm.Reynolds@appcenterpfllink.onmicrosoft.com