Representational State Transfer (REST) Web Services V1

HTTP Methods

GET, POST, PUT, DELETE

Authentication

If the customer is using the Basic Authentication, the steps in the Setting Up Integration Users with Basic Authentication topics must be followed to create an Integration user and retrieve the Auth token.

If the customer is using OAuth Authentication, the steps in the Setting Up Integration Users with OAuth Authentication topics must be followed to create the Integration user and retrieve the Auth token.

Prerequisite for invoking any REST service - Integration user and JWT Auth token should be available.

Integration User:

All REST services should be accessed via Integration User.

Token can now be used in all REST services for authentication mechanism. All REST services should have the following set in the 'Header'.

Header - Sample

Key	Value
Authorization	Bearer eyJ0eXAiOiJEQiJ9.eyJ1c2VybmFtZSI6IiQkZGVsdDMifQ==.02318C44-9F3A-F931-3F14-C6FA7576F55E7D8D9975C46B5805179BD10D890DF15F

Note: Validity of the token is as given in the login. The same can be re-used for subsequent REST requests until the expiry date.

User can change Expiry Date to minutes, hours, and days in UI. REST will retain those settings and generate new token with given Expiry Duration in the UI.

If the Authorization token is not valid/correct for subsequent REST requests, those services will throw 401 status code (Unauthorized).

If the Authorization token is correct but the user for whom token is generated does not have permission for any REST request, that service will throw 403 status code (Forbidden).

For every login REST service initiated, a new token is generated, old token is invalidated.

Data

If integration interface is defined for BP, integration form will be used for this service; otherwise, all custom DEs defined in the form will be used.

For update, specify only the DEs to be updated.

Data Format

Input and output data will be in JSON format. Set HTTP header Content-Type : application/json.

Data Transfer

HTTP request body will be used to send the JSON data.
Multipart/form-data will be used to handle files.

Default Integration User

For migrating customers before 19.7, default integration user with company shortname and authcode with access to existing system services.

Default cloud user has 500 days Auth token validity.

Standards

Get Method

Will be used to request data from a source when no parameters are sent in the body.

Note: Do not use the word "get" in the URL.

URL Encoding GET call parameter values

All parameters in GET call must be URL encoded.

For Postman REST client, use following code in “pre-request Script” tab, which will trim extra spaces in params key and encode special characters in params value.

pm.request.url.query.all().forEach( (param) =>

{

param.key = param.key.trim();

param.value = encodeURIComponent(param.value );

}

);

POST Method

POST can be used to retrieve data with parameters in body.

Can be used for CREATE, Retrieve data with parameters.

For example, getBprecordlist - bpname is mandatory and needs to be a sent in request body.

Note: Do not use the word "create" in the URL.

To distinguish create and get data with parameters, term list can be added in the URL.

PUT Method

PUT is used update data.

Note: Do not use the word "update" in the URL.

Logging:

All REST operations get audited in internal audit log table (not accessible to User, as it is not business case audit logs).

A background CRON job is created to run on every SUNDAY 4:00AM (server time zone) which will purge older REST internal audit logs which goes beyond 25000 audit rows.

IP Filtering:

Customers can provide the list of IP addresses that can consume REST Web Services (V1 or V2). The IP Filtering option is available in the portal in the IP Allowlist tab of the Company Settings node.

If the Allow API access only from below IP addresses option is checked in Company Settings, the remote host will be validated based on their IP Version.

If the remote host is IPv4 version, it will be checked against the list of IP addresses provided in the IPv4 text box.
If the remote host is of IPv6 version, it will be checked against the list of IPs provided in the IPV6 text box.
If IP addresses are provided in CIDR format, the remote host IP will be checked against all addresses that come in the range.

Additional Information

If the endpoint URL has a project number and the project number contains special characters (such as / \ : * ? " < > |), you must change those special characters to URL escape characters.

Example

Project number with a special number sign (hash) such as 2020#7 must be changed to 2020%7.

Note: You can use a browser to access the list of URL escape characters.