WebAPI Endpoint

Defines the endpoints the WebAPI module listens to for incoming requests and is the first step when setting up an integration for WebAPI.

The WebAPI screen allows you to define the endpoints as well as Assign Web Users.

Before defining the endpoint it is important to be familiar with the fundamentals of an Anatomy of an http Request & response.

It is important to note that all changes (additions, changes, deletions) to API endpoints are reflected immediately.

WebApi Endpoint Setup

Endpoint Id

The unique Id given to the endpoint.

Description

The endpoint description.

Http Method

The http method the endpoint will listen.

• GET

  • Used for Query type operations to obtain/return a resource e.g. a customer record, open orders, tracking ids.
  • Requests do not typically have a body, but either have a series of urls paths or request parameters to indicate which resource(s) to return.

• POST

  • A request is used to create or add a resource such as a customer, invoice, order, but they may also be used to trigger an integration.
  • Requests (typically) have a body which is the data that should be added/created.

• PUT

  • Requests are similar to POST requests but are typically used to replace or update a resource.
  • Requests also have a body, which is the data to be replaced or updated.
  • Requests typically have a parameterised URL to indicate the resource being updated/replaced.

• POST/PUT

  • Request allow you to define a single integration which listening to both methods i.e. to have a single integration to either create or update a resource.

Route

The route or path for the endpoint. The path (or value entered) forms the last part of the full url, where the server and first segment of the path are defined by the server and IIS Application Path respectively.

The route can either be static, or can be parameterised.

Parameterisation

IMan supports parameterisation of the route/path with tokenised path segments and query parameters.

Each parameter whether path or query appears as a field on the WebAPI reader.

Path Tokenisation

Path Tokenisation is mostly used in PUT requests to specify the resource to update/replace.

orders/{customer}

IMan support multiple tokens for example.

{customer}/addresses/{addressId}

Query Parameters

Parameters are mostly used in GET requests to supply additional criteria to the resource being queried.

orders?startDate={startDate}&endDate={endDate}

POST/PUT Requests

When the method is set to POST/PUT there separate routes for POST and PUT.

Allow Anonymous Requests

When selected the endpoint will allow unauthenticated requests.

When deselected the request must be authenticated. See security.

User Property Set

The Properties & Property Sets users will be associated.

Request Timeout

The time in seconds the endpoint must complete before the request is aborted.

Result Status Code

The HTTP Status code to return when a request succeeds. The default is 200 which is the standard OK result.

Error Message Path

The path for any error message.

Request Throttling

When set to Leaky Bucket requests will be limited to the number set per second.

Otherwise all requests will be accepted and the limiting factor will be the server.

Trace

Traces the output.

Assign Web Users

To maintain the users associated with an endpoint click the button to the corresponding endpoint.

Endpoint Property Set and User Properties

When a user is associated with an endpoint, the properties from the endpoint's associated property set are assigned to the user. No change/affect is made where a user is associated with multiple endpoints with the same property set.