HTTP Methods
GET, POST, PUT,DELETE
Authentication
Pre-requisite 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.
Create an Integration User at Company Workspace → User Administration → Integration User.
Make sure the integration user has the required module permissions enabled.
Integration user token expiration can be set from the Integration user UI. User can create, update Auth Token expiry date to - days, hours and minutes.
1 to 500 is a valid value for Expiry Duration.
By default the value is set to 180 days.
Auth Token:
authentication token is required to access the rest services.
Token is set to be valid for date available in the response.
The token can be obtained by the below url.
http://<host>:<port./ws/rest/service/v1/login
Method - GET
Headers -Authorization:Basic <Basic Auth of integration user>
(To Generate one via Postman rest client - Go to 'Authorization' tab → choose 'Basic Auth' in 'Type' dropdown → Enter Integration user name and password -. Click on 'Update Request'. This generates the necessary Authorization header in 'Headers' tab.)
If the user name/password combination shared in the above Authorization Header is not valid/correct, the service throws 401 status code(Unauthorized)
Other conditions that are checked are - Integration user has to be active.
The expiry date is displayed as per the user date format preferences set in the Integration UI.
Sample response -
{
"expiryDate": "05/18/2021",
"Timezone": "(UTC-08:00) Pacific Time (US & Canada)",
"expiryTime": "05/18/2021 11:44 AM",
"status": 200,
"token": "eyJ0eXAiOiJEQiJ9.eyJ1c2VybmFtZSI6IiQkZGVsdDMifQ==.02318C44-9F3A-F931-3F14-C6FA7576F55E7D8D9975C46B5805179BD10D890DF15F"
}
Token can now be used in all rest services for authentication mechanism. All rest services should have the below set in the 'Header'.
Header - Sample
Key | Value |
|---|---|
Authorization | Bearer eyJ0eXAiOiJEQiJ9.eyJ1c2VybmFtZSI6IiQkZGVsdDMifQ==.02318C44-9F3A-F931-3F14-C6FA7576F55E7D8D9975C46B5805179BD10D890DF15F |
Notes:
- 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 honor 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 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 then 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.
Standards
Get Method -
Will be used to request data from a source when no parameters are sent in the body.
Note: Do not use 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 below code in “pre-request Script” tab, that 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 need to be a sent in request body.
Note: Do not use 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 word "update" in the url.
Logging:
All REST operations on Unifier gets 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 have the ability to provide the list of IP addresses which can consumer Unifier REST Webservices(V1 or V2). IP Filtering option is available in Unifier portal in Company Properties - Security Tab.
If the 'IP Filtering Policy' field is checked in company properties, then the remote host will be validated based on their IP Version
1. If the remote host is IPv4 version then it will be checked against the list of IP addresses provided in the IPv4 text box.
2. If the remote host is of IPv6 version it will be checked against the list of IPs provided in the IPV6 text box.
3. If IP addresses are provided in CIDR format then the remote host IP will be checked against all addresses that come in the range.