Platform Integration

THG Connect Integration Platform is THG’s API solution offering a range of products suited for your business’s needs, this documentation walks you through the steps to start your journey with THG.

Concepts

Console

The THG Connect Console will allow you to setup your organisation and get you started on the platform.

Product

THG APIs provided by the THG Connect Integration Plaform are grouped into products, a product represents a business workflow e.g. Fuflfilment (THG Fulfil). APIs within a product are directional, they are designed to be used by either a consumer or a provider (view partnership section for more on consumers and providers); e.g. inventory item (entity) is from consumer -> provider, consumers create/modify/delete inventory item and the provider consumes the events (see event driven section below) to trigger logic. The consumer in this example would be considered the owner e.g. /<consumer>/v1/inventory-item, when the direction is reversed provider -> consumer the owner would be the provider e.g. /<provider>/v1/asn

An API is made up of a hierarchy of entities, this hierarchy is represented in the path of the resource, e.g. /<owner>/v1/inventory-item/<inventory item ID>/approval, Approval entity is a child of Inventory Item, resulting in approval being created on a inventory item resource provided by the inventory item ID in the path.

Statuses

A status is a specialised entity which has a set of states, these are designed to represent a status of its parent entity. For example: Approval is a status of Inventory Item, an inventory item submitted by a consumer is then approved by provider, resulting in the approval being state Approved or Not Approved. Each state of status can have its own payload allowing for additional information to be provided alongside a status e.g. why the inventory item was not approved.

REST API

REpresentational State Transfer (REST) is an architectural style used for building web-based APIs, it follows six principles (read more). All THG APIs on the THG Connect Integration Platform will conform to these REST principles.

Entity Updates

Updates for entities will use PUT and only entities which are mutable will have an update endpoint. PUT is used over PATCH to ensure idempotency, to update an entity the full entity must be send in the body of the request as it overwrites the data which is there.

Filtering & Pagination

Filtering and pagination is available on the GET ALL endpoints. A request without any query parameters will by default return the first page of size 10 with no filter, to provide custom values/cycle through the pages you can provide page[number] (integer) and page[size] (integer) as query parameters, e.g. https://api.developer.thgingenuity.com?page[number]=10&page[size]=100. A page with no entries will return a successful response with an empty list ([]).

Filtering can be applied to a GET ALL request using the filter query parameter, this uses Simple Query Language made up of comparison statements (format: <key><comparison operator><value>, e.g. orderId='123456') joined using conjunction operators (e.g. createdAt>'2024-10-15T13:45:00' and orderId='123456'). Grouping of comparison statements can be done using brackets (()) e.g. https://api.developer.thgingenuity.com?filter=(createdAt>’2024-10-15T13:45:00’ and createdAt<’2024-10-15T16:45:00’) and orderId=‘123456’this will look for order ID123456in a created time range between2024-10-15T13:45:00and2024-10-15T16:45:00, date time formats must conform to this pattern: yyyy-mm-ddThh:mm:ss`.

Conjunction Operators:

	Description
AND	AND operator requires both comparison statements to be true
OR	OR operator requires only one comparison statement to be true

Comparison Operators:

	Description
>=	Greater than or equal to
<=	Less than or equal to
!=	Not equal
=	Equal
>	Greater than
<	Less than

Event Driven

Any POST, PUT and DELETE requests made to the THG Connect Integration Platform THG APIs will send out a DataChangedEvent (read more) these events can be consumed using subscriptions (read more).

The above diagram is a simplistic visulisation of the intended event driven approach, a consumer and provider (view partnership section for more on consumers and providers) create/modify resources as part of a product’s workflow these actions generate events which can be consumed by the other members of a partnership triggering event based logic in the consumer/provider’s system.

Response Schema

All responses returned from any THG API on the THG Connect Integration Platform are application/json and conform to JSON API Specification v1.1.

Platform Invitation

After consulting our solutions experts and choosing a product, you will receive an invitation to the platform. This invitation will create your organisation and give you access to the platform’s tool to manage your products, members and authentication.

Partnership

A partnership on the THG Connect Integration Platform defines a relationship between you and a provider/providers of a product.

There are two primary roles in a partnership: the consumer - an organisation consuming a product - and the provider - an organisation/entity providing a product’s services.

For example for the THG Fulfil Product, a possible provider would be THG, THG would be providing the services of the THG Fulfil product. A organisation can then come along and consume the THG Fulfil product by partnering with THG, making them the consumer.

To setup a partnership, login into the platform’s tool with your credentials and navigate to the ‘Products’ on the left and select the product you wish to setup.

To create a new partnership with a provider navigate to the configuration section and use the ‘Set up new partnership’ button.

Select the product you wish to use, then fill in the list of provider organisations you are in partnership with.

Submit the form to create a new partnership for this product, which can be managed on the product page under the configuration section.

Authentication

All APIs on the THG Connect Integration Platform require Bearer OAuth using JSON Web Tokens (JWT), these tokens come with an expiry time and it is preferred that a single token is used for API calls in the window the token is valid. Tokens are requested using a service account, to setup your first service account log into the platform tool and navigate to the ‘Settings’ page on the left.

Use the ‘Add API Client’ button to navigate to the setup page.

Once all the input boxes are filled in submit the form to create your service account.

The newly created service account will now appear, here you can use the menu on the right of the service account record to view token information.

To request a token you can use the provided HTTP request example, for integration with the token endpoint you will need the token url https://frontier-production.uk.auth0.com/oauth/token, the audience https://api.developer.thgingenuity.com both taken from the HTTP request example; and the client ID and client secret from the information window. All this information will be dependent on the environment of THG Connect Integration Platform you are using, ensure you consult your platform tool for the correct information.

HTTP Request:

curl --location '<authUrl>/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
    "client_id":"<client_id>",
    "client_secret":"<client_secret>",
    "grant_type":"client_credentials",
    "audience":"<apiUrl>"
}'

Response:

{
    "access_token": "<access_token>",
    "expires_in": 86400,
    "token_type": "Bearer"
}

The two main elements of the response for an integration are the access_token this is your JWT used to authenticate you request, it must be sent in the headers 'Authorization': 'Bearer <access_token>' of every request to any API in the THG Connect Integration Platform. The second element is the expires_in this is the lifetime of the token in seconds, after it expires a new token must be requested.

With a partnership created and authentication setup you can start using the APIs.

Subscription

For your integration with the platform you may require usage of the Events API, here you can manage you subscriptions to your events. Further information on the structure and types of events click here.

THG Connect Integration Platform offers two methods of consuming your events from your subscription: the first is long polling (preferred method) and the second is webhooks. All subscriptions can be polled default, for webhooks they must be provided in the subscription on creation.

When creating a subscription you provide a unique subscription ID, e.g. testsubscription. Multiple instances/nodes/application can poll the same subscription, with each poll the individual nodes will get different events, distributing the events across nodes. To achieve this each event has a 30 second window after polling where it is hidden from polling, the node which polled the event must confirm the event in this window to prevent the event being polled again. Alternatively, if you require each instance/node/application to recieve all events you can create a subscription for each instance, e.g. testsubscription1, testsubscription2, this will duplicate the events to all subscriptions.

Long Polling

Long polling is a common pattern used for event consumption. It requires the client system to poll (Poll Endpoint Docs) the THG Connect Integration Platform at regular intervals asking for any new events. Events will never be removed from the queue through polling. Once the client system has recieved the event it must confirm the event (Confirm Endpoint Docs) to remove it from the queue.

Webhooks

The webhook pattern notifies a clients system via webhook of any new events. This notification will never remove the event from the queue. The client system must confirm the event (Confirm Endpoint Docs) to remove it from the queue.

Members

Within your organisation you may wish that more than one user has the ability to manage: users, authentication and products; to do this you can add a member within the platform tool. Login and navigate to the ‘Settings’ page on the left.

Use the ‘Invite a new member’ button in the to navigate to the setup page.

To setup the new user all that is required is their email; once the form is filled in and submitted a new user is created. The new user will receive an email to register with the platform tool, once they have completed that step they will be able to login and manage the organisation.

Sandbox

NOTE: Sandbox behaviour is not fully defined please contact us for more information if being used

There may be situations where your organisation wishes to test behaviour of the API using test Entities We have provided a Sandbox which has custom behaviour based on what Entities you hit our APIs with. The sandbox behaves the same in all environments and runs alongside your production Entities, meaning you don’t need to worry about setting up a test environment.

For example, there is a Sandbox for the Inventory API in the THG-Fulfil product which will automatically approve an Inventory item if its sku equals test_sku. This happens automatically out of the box once you are onboarded onto the sandbox.

To get access to the sandbox, you need to add the sandbox organisation as a provider to whichever product you want to use it for (the sandbox is essentially another organisation on the platform and you can treat it as such). Once added, you will automatically get access to the sandbox behaviour and you can start creating/updating/deleting entities in your testing.

Documents

Certain APIs will require your organisation to upload some documents, such as a pdf file for Hazmat Documentation. We have provided a Document API for this flow which handles upload and referencing.

To upload a document and reference it in the THG-Fulfil API for example, you will first need to do a POST request to the Document API with the filename you wish to upload. This will return a Reference String back (i.e. thg:document:example-organisation@4f2929b5-2512-48da-be97-c362cc452dc8) aswel as a custom Presigned-URL which you can upload your document to. You then need to upload your document to this presigned URL by doing a POST request ensuring you have included all the required fields (see examples in Document API reference). Once you have uploaded the actual document to this Presigned-URL, you will be able to reference the document in our other APIS. I.e. you may include a hazmat document in the THG-Fulfil API like this {"hazmat_documentation":"thg:document:example-organisation@4f2929b5-2512-48da-be97-c362cc452dc8"}.