Kourier Integrator User Guide

Kourier User Guides > Using Kourier REST

Introduction to Kourier Integrator REST Resources

With Kourier you can create a resource-oriented application programming interface (API), based upon the REST open standard architecture, which allows you to retrieve and update information in your U2-based application in real-time.

Common Characteristics of REST Resources

The following characteristics apply to all Kourier REST resources:

You access a resource by sending an HTTP request to the Kourier REST Gateway server. The server replies with a response that either contains the data you requested, or a status indicator, or both.
All resources are located under a base URL that you use to access the Kourier REST Gateway.
You request a particular resource by appending a particular path to this base URL that specifies the resource that you wish access.
All resources require that you specify certain HTTP header fields as described below.
All resources may return any of the status codes listed in HTTP Status codes below.

Types of REST Resources

Developers create a REST API for their application by creating one or more REST Resource Specifications that define the resources available within the integration and how those resources are implemented as either a Kourier Export Specification (Outbound) or a Kourier Import Specification (Inbound).

This topic describes the Kourier REST resources that are configured as a server. Contact your Kore Technologies representative to learn how Kourier can be used to build a REST based client.

Outbound REST Resource

An outbound REST resource is implemented as a Kourier Export Specification. A REST Export Specification allows you to define specific parameters for the resource, reference those parameters in the SELECT statement used to retrieve information from the U2 database or while creating the response for the resource. Parameters are passed in the URL as query strings.

Here is an example GET URL: http://<base-url>/RWS/CUSTOMER/SEARCH?NAME=A]&CITY=SAN

Any parameters can be accessed using a Kourier substitution string. For example, if you have a parameter named “NAME” you can access that parameter using the string {%NAME} in a SELECT statement.

If you need to access a parameter from UniBASIC code you can use the KMK.GETHDR subroutine as follows: CALL KMK.GETHDR(RMLO.EXPORT.HDRS,’NAME’, NAME)

When creating a GET type resource/sub-resource, Kourier has several built-in capabilities that add to the utility and usability of the REST resource. These capabilities include:

Query Parameters

Kourier allows the API designer to create any number of query parameters when creating a GET request. Each query parameter can specify minimum/maximum length, if the parameter is required, and edits such as dates, numeric, lookups for which the value of the query parameter must conform. A query parameter’s value is available as a dynamic substitution at run-time.

Query Wild Cards

The API consumer can include wildcard characters in query parameters to facilitate searching for partial matches in the data. Use the “[“ character for an ending with search, the “]” character for a beginning with search and the “[]” characters for a containing with search.

Selecting/Filtering

Kourier leverages the native SELECT capabilities in U2 to support robust selection criteria when creating GET requests. You can define the SELECT statement with placeholders which are resolved dynamically at run-time based upon the value of a query parameter included in the URL. To support complex selection criteria, you can programmatically build the SELECT statement at run-time.

Limiting Fields Returned in a Request

The API consumer may not always need the full representation of a resource. Kourier allows the API consumer to select which fields are returned in a GET request by specifying the “Fields” query parameter. This parameter accepts a comma delimited list of field names. By doing this, the API consumer can minimize network traffic and speed up their own usage of the API.

Dynamic Sorting

Kourier allows the API consumer to sort the items returned in a request by specifying the “SortBy” query parameter. This parameter accepts a comma delimited list of field names to accommodate complex sorting requirements. A descending sort by can be specified by preceding the field name with a minus (-) character.

Pagination

In many cases, a GET request may return a large number items in the result. Kourier automatically limits the results returned to either the system default value (usually 100 items) or the value configure in the GET request using the EXPORT-MAX-ITEMS keyword. The API consumer can “walk” the result set by using the “Page” and “PerPage” query parameters along with the information returned in the X-Count-Items header field.

Inbound REST Resource

An inbound REST resource is implemented as a Kourier Import Specification. A XML to U2 Import Specification allows you to define specific parameters, which are passed in the URL as query strings.

If you need to access a parameter from UniBASIC code you can use the KMK.GETHDR subroutine as follows: CALL KMK.GETHDR(QUERYHDRS$,’CustomerNo’, CUSTOMER.ID)

Security for REST Resources

To access a Kourier REST API, the user of the API must provide a Kourier REST Gateway user account name and the credentials associated with that Kourier REST Gateway connection. We recommend that you create at least one Kourier REST Gateway user account which is NOT the standard accountused to access your U2 account via the Kourier REST Gateway. If there are multiple users of the API, we recommend a separate user accountfor each user. This will allow you to revoke access to the API user without effecting access to the Kourier REST Gateway or other users of the API. Remember, you must create unique credentials (user/password) for each Kourier REST Gateway account for this approach to be workable.

In the client application that is accessing the REST API, the connection and credentials MUST be passed in the X-Connection and Authorization HTTP request header fields.

HTTP Methods

You use standard HTTP verbs to indicate the type of request you are making. These HTTP verbs directly correlate with the concept of database CRUD (Create, Read, Update, and Delete) operations.

HTTP Verb	Specification	Description
GET	Export	Used to read information from your U2-based application via a U2 to REST Export Specification.
POST	Import	Used to insert a record into your U2-based application via a XML to U2 Import Specification.
PUT	Import	Used to update a record into your U2-based application via a XML to U2 Import Specification.
PATCH	Import	Used to either insert or update a record into your U2-based application via a XML to U2 Import Specification.
DELETE	Import	Used to delete a record into your U2-based application via a XML to U2 Import Specification.

Reserved Query Parameters

When making a request via the HTTP GET verb, query parameters can be used to pass additional information to the Kourier Export Specification responding to the request. Query parameters are reserved solely for the use of the API designer except for the following:

Query Parameter	Required	Description
Fields	No	Used to limit the number of fields returned in the request result. This query parameter accepts a comma separated list of fields to include in the request result. If this query parameter is not included in the URL, all fields will be returned.
OutputAs	No	Used to control the format of the request result. Possible values are: TAB, XML, JSON, TILDE, PIPE, CSV, HTML, FIXED. If this query parameter is specified, it overrides the accept header in the request.
Page	No	Used to control pagination of requests that return a large number of items. This query parameter takes a numeric value representing the first item to return in the record set.
PerPage	No	Used to control pagination of requests that return a large number of items. This query parameter takes a numeric value representing the number of items to return in the result set. This number cannot be greater than the value returned in the X-Max-Items Header field.
ResourceID	No	Contains the requested U2 natural key for certain type of URLs.
SortBy	No	Used to control the order in which items are returned in the request result. This query parameter accepts a comma separated list of field names each with a possible unary negative (-) to imply descending sort order.
X-Connection	Yes	The name of the Kourier connection to use for this request.
X-HTTP-Method-Override	No	For clients that only support HTTP GET and POST methods, this query parameter allows you to override the HTTP method. This query parameter is only valid on POST requests.

HTTP Request Headers

Each request must contain certain required and optional information needed by Kourier to process the request. In some cases this information may be passed using the Reserved Query Parameters and in other cases this information must be passed in the HTTP header. Any HTTP header not in the list below will be ignored.

Header	Type	Required	Description
Accept	ALL	No	Used to control the format of the request result. Possible values are: Applications/JSON, Applications/XML, Text/HTML, Text/CSV, Text/Tab/Separated/Values.
Authorization	ALL	Yes	The user ID and password associated with the Kourier connection base 64 encoded. Basic Auth only.
X-HTTP-Method-Override	POST	No	For clients that only support GET and POST HTTP methods, this request header allows you to override the HTTP method. This header is only valid on POST requests.
X-Connection	ALL	Yes	The name of the Kourier connection to use for this request.

HTTP Response Headers

Kourier may return one or more of the response headers described below:

Header	Request Type	Always Returned	Description
Cache-Control	ALL	Yes	Should always return no-cache
Content-Length	ALL	Yes	The length of the response body in bytes.
Content-Type	ALL	Yes	The MIME type of this content
Date	ALL	Yes	The date and time that Kourier returned results to the website. Example: `Date: Tue, 15 Nov 1994 08:12:31 GMT`
Expires	All	Yes	Should always return -1
Links	GET	No	Includes URLs to navigate to the first, previous, next, and/or last page of a result set. A link header is only returned if the number of items selected exceeds the EXPORT-MAX-ITEMS parameter. The only time the links are provided is if the X-Count-Items is greater than the X-Max-Items header.
Pragma	ALL	Yes	Should always return no-cache
Server	ALL	No	The web server software that managed the request. This header may be omitted based upon the websites configuration.
Status	ALL	Yes	The HTTP status of the response (see response code below)
X-AspNet-Version	All	No	ASP.NET version. This header may be omitted based upon the websites configuration.
X-Kourier-Version	ALL	Yes	Kourier version that processed the request.
X-Count-Items	GET	Yes	Indicates the total number of items available in the request result (see also: Page, PerPage query parameters).
X-Max-Items	Get	Yes	Indicates the maximum number of items that can be returned in a single request result. (see also: Page, PerPage query parameters)
X-Powered-By	ALL	Yes	Should always be ASP.NET

HTTP Response Codes

In most cases, Kourier will use standard HTTP response codes to indicate the status of the request.

Code	Description
200	Request was processed successfully. GET method only.
201	Request was processed successfully. Resources were created or modified. POST, PUT, PATCH or DELETE methods.
204	Request was processed successfully but no data returned. GET method only.
400	There was a problem processing the request. The response body will contain additional information.
401	The request was refused because the authentication information was not provide or is not valid.
404	The requested resource could not be found.
405	The requested HTTP method is not supported by the resource.
500	Server processing error.

HTTP Responses Body

All responses (successful or not) for all POST, PUT, PATCH, and DELETE requests, and all non-successful GET requests, include a status response type in the response body, in the same format.

Response Element	Always	Description
http_code	Yes	A standard HTTP status code that indicates success or failure.
http_subcode	No	Indicates that the application generated an error message.
message_code	No	Indicated that Kourier encountered a fatal error. This code corresponds to an item-id in the KT-MESSAGES file.
message	No	The text of the message.
record	No	Indicates which record was affected by a POST, PUT, PATCH or DELETE request.
record@ResourceFile	Yes	Indicates the name of the file affected by a POST, PUT, PATCH or DELETE request.
record@ResourceID	Yes	Indicates the U2 ID of the record affected by a POST, PUT, PATCH or DELETE request.
record@RemoteID	Yes	Indicates the remote ID of the record affected by a POST, PUT, PATCH or DELETE request.
record@href	Yes	Provides the link to the resource that was created or modified.
record@loaded	Yes	The resource was created or modified without error.
record@operation	Yes	Indicated if the resource was Inserted, Updated or Deleted.
record/error	No	Contains the application error message text.