Intellicus supports REST calls for integrating Intellicus data and functions into an application. This section of document discusses the Intellicus integration architecture of REST APIs along with their use cases to perform CRUD operations and apply transformations on various Reporting use cases. These REST services enable you to log in, and then perform various Administrative activities in Intellicus.
REST stands for Representational State Transfer. It relies on a stateless, client-server, cacheable communications protocol — and in virtually all cases, the HTTP protocol is used.
RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data.
Rest Integration Architecture
Response Code
The intellicus API attempts to return appropriate status codes for every request.
| Response Code | Response Message |
| 200 | OK |
| 503 | TIMEOUT OCCURED. LOGIN AGAIN. |
| 401 | UNAUTHORIZED ACCESS |
| 404 | RECORD NOT FOUND |
| 412 | PRECONDITION FAILED. PARAMETER MISSING |
| 500 | FAILED |
Accessing the REST API
We have created REST clients using JERSEY client APIs that we ship with Intellicus installer. To use those intellicus Restful APIs, we used below jersey jars :
- jersey-core.jar
- jersey-client.jar
- java-json.jar
URL
| URL | Action | Description |
| http://<host>:<port>/rest/login | POST | Login into Intellicus Report Server using this API. |
| http://<host>:<port>/rest/logout | GET | Logout from Intellicus Report Server using this API. |
| URL | Action | Description |
| http://<host>:<port>/rest/org | GET | List of all the organization. |
| http://<host>:<port>/rest/org/{orgId} | GET | Return the object of the orgId specified. |
| http://<host>:<port>/rest/org | POST | Create organization of the orgId specified. |
| http://<host>:<port>/rest/org/{orgId} | DELETE | Delete the organization specified by orgId. |
| URL | Action | Description |
| http://<host>:<port>/rest/user | GET | List of all the users. |
| http://<host>:<port>/rest/user/{userId} | GET | Return the object of the user Id specified. |
| http://<host>:<port>/rest/user/{userId} | DELETE | Delete the user specified by user Id. |
| URL | Action | Description |
| http://<host>:<port>/rest/role | GET | List of all the roles. |
| http://<host>:<port>/rest/role/{roleId} | GET | Return the object of the role Id specified. |
| http://<host>:<port>/rest/role/{roleId} | DELETE | Delete the role specified by role Id. |
| URL | Action | Description |
| http://<host>:<port>/rest/category | GET | List of all the categories. |
| http://<host>:<port>/rest/category/{categoryId} | GET | Return the object of the role Id specified. |
| http://<host>:<port>/rest/category/subcategories/{categoryId} | GET | List of all the Sub categories in a category. |
| http://<host>:<port>/rest/category/{categoryId} | DELETE | Delete the category specified by category Id. |
| http://<host>:<port>/rest/category | POST | Create a new category. |
Authentication
Login
This API is needed to authenticate a user. On successful authentication, this REST call returns with a session id that can be further used to request any other REST call.
Pattern
/rest/login
Method
POST
Request body
| content type* | application/x-www-form-urlencoded |
Parameters
| Name | Description | Type | Default |
| username* | User present in Intellicus Repository. The user must have the appropriate privileges configured for the actions he/she is going to take using the API calls. | formdata | None |
| password* | Password associated with the username. | formdata | None |
| organization* | The organization of the user to be authenticated | formdata | None |
| tokenTimeOut | Number of minutes of inactivity after which the login session will end. After this timeout login request has to be resent for any further request. | formdata | 30 |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
POST http://<IP>:<Port>/intellicus/rest/login
Post Paramters
username:John
password: abcd1234
organization: Intellica
tokenTimeOut: 20
Note: Users of organizations whose authentication type is Host Application cannot acess REST APIs.
API results with sessionid enclosed in a success tag, in case of successful authentication.
API results with an error message, in case of any error.
The sessionid attribute of this user should be passed in other APIs in subsequent requests for User Identification.
Note: Login will return a sessionid as a response.
Ex: <SUCCESS> New organization – Advanced tab </SUCCESS>, and this sessionid will be used in all the other REST API’s as a header parameter.
Setting sessionId
This session Id is the one that is established using the login call.
Header Paramter
Session- > a session in Intellicus on which this call will run.
Logout
This API is needed to logout from REST API access.
This call ends a session identified by the sessionid and expires that session. This session is the one that was established using the login call.
Pattern
/rest/logout
Method
GET
Parameters
| Name | Description | Type | Default |
| sessionid* | Session in Intellicus on which this call will run. | Request header | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
GET http://<IP>:<Port>/intellicus/rest/logout
API Result with Status #SUCCEEDED, if request was successful. API Result with Status #FAILED, if request had failed.
Organization
getOrganizationList
This API is used to get the list of all organizations present in the Intellicus repository.
Pattern
/rest/org
Method
GET
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
GET http://<IP>:<Port>/intellicus/rest/org
API Result with XML/JSON containing list of the organizations.
GetOrganizationObject
This API is used to get the object of organization present in the Intellicus repository.
Pattern
/rest/org/{orgId}
Method
GET
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header | None |
| orgId* | The ID of the organization whose object we want to get. | Path | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
GET http://<IP>:<Port>/intellicus/rest/org/TestOrg
createOrganization
This API is required to create new organization.
Pattern
/rest/org
Method
POST
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working
|
Request header | None |
| OrgId* | Name of Organization you want to create. | formParam | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
POST http://<IP>:<Port>/intellicus/rest/org
Post Paramters
- OrgId:TestOrganization
deleteOrganization
This API is used to delete an existing organization from the Intellicus repository.
Pattern
/rest/org/{orgId}
Method
DELETE
Request body
| content type* | application/x-www-form-urlencoded |
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header
|
None |
| orgId* | The ID of the organization which is to be deleted. | Path | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
DELETE http://<IP>:<Port>/intellicus/rest/org/TestOrg
API Result with Status #SUCCEEDED, if request was successful. API Result with Status #FAILED, if request had failed.
Category
getCategoryList
This API is used to get the list of all categories present in the Intellicus repository.
Pattern
/rest/category
Method
GET
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
GET http://<IP>:<Port>/intellicus/rest/category
API Result with XML/JSON containing list of the categories.
getSubCategoryList
This API is used to get the list of all Sub categories presenting the given Category in the Intellicus repository.
Pattern
/rest/category/categoryId/{categoryId}
Method
GET
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header
|
None |
| categoryId* | The ID of the category whose sub category we want to get. | Path | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
GET http://<IP>:<Port>/intellicus/rest/category/categoryId/571937DE993490CFF371470A44B7E
API Result with XML/JSON containing list of the sub categories inside a category.
getCategoryObject
This API is used to get the object of category present in the Intellicus repository.
Pattern
/rest/category/{categoryId}
Method
GET
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header
|
None |
| categoryId* | The ID of the category whose object we want to get. | Path | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
GET http://<IP>:<Port>/intellicus/rest/category/571937DE993490CFF371470A44B7E
API Result with Status #SUCCEEDED, if request was successful. API Result with Status #FAILED, if request had failed.
createCategory
This API is required to create new category.
Pattern
/rest/category
Method
POST
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header | None |
| categoryName* | Name of category you want to create. | FormParam | None |
| isPublic* | Category should be public or not.(value should be true/false) | FormParam | None |
| isHidden* | Category should be hidden or not.(value should be true/false) | FormParam | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
POST http://<IP>:<Port>/intellicus/rest/category
Post Paramters
categoryName: TestCategory
isPublic: true
isHidden: false
API Result with Status #SUCCEEDED, if request was successful. API Result with Status #FAILED, if request has failed.
deleteCategory
This API is used to delete an existing category from the Intellicus repository.
Pattern
/rest/category/{categoryId}
Method
DELETE
Request body
| content type* | application/x-www-form-urlencoded |
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header
|
None |
| categoryId* | The ID of the category which is to be deleted. | Path | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
DELETE http://<IP>:<Port>/intellicus/rest/category/571937DE-993490CFF37-1470A44B7E
API Result with Status #SUCCEEDED, if request was successful. API Result with Status #FAILED, if request had failed.
User
getUserList
This API is used to get list of users for the given organization in the Intellicus Repository. User is required to provide the organization id, whose list of users, the requesting user wants to retrieve.
Pattern
/rest/user/
Method
GET
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header
|
None |
| orgId* | Name of organization whose users list is to get.
|
QueryParam | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
GET http://<IP>:<Port>/intellicus/rest/user?orgId=TestOrg
API Result with XML/JSON containing list of users for the given organization Id.
getUserObject
This API is used to get the object of user present in the Intellicus repository.
Pattern
/rest/user/{userId}
Method
GET
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header
|
None |
| userId* | The ID of the user whose object we want to get. | Path | None |
| orgId* | The ID of the organization whose user’s object we want to get. | QueryParam | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
GET http://<IP>:<Port>/intellicus/rest/user/User1?orgId=TestOrg
API Result with Status #SUCCEEDED, if request was successful. API Result with Status #FAILED, if request had failed. The XML contains System privileges and access rights. Details of System privileges and access rights are present in Appendix-2.
createUser
This API is required to add new user in the Intellicus repository.
Pattern
/rest/user
Method
POST
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header | None |
| userId* | Name of user you want to create. | formdata | None |
| password* | Password to be assigned | formdata | None |
| orgId* | Name of the organization in which you want to add user. | formdata | None |
| isHostAppAuthentication* | To set authentication type as host app or not.(value should be true/false) | formdata | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
POST http://<IP>:<Port>/intellicus/rest/user
Post Paramters
userId:Mike
password: abcd1234
orgId: Intellica
isHostAppAuthentication: false
API Result with Status #SUCCEEDED, if request was successful. API Result with Status #FAILED, if request has failed.
deleteUser
This API is used to delete an existing user from the Intellicus repository.
Pattern
/rest/user/{userId}
Method
DELETE
Request body
| content type* | application/x-www-form-urlencoded |
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header | None |
| userId* | The ID of the user which is to be deleted. | Path | None |
| orgId* | The ID of theorganization of which user is to be deleted. | QueryParam | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
DELETE http://<IP>:<Port>/intellicus/rest/user/User1?orgId=TestOrg
API Result with Status #SUCCEEDED, if request was successful. API Result with Status #FAILED, if request had failed.
Role
getRoleList
This API is used to get the list of all Roles present in Intellicus Repository.
Pattern
/rest/role/
Method
GET
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header
|
None |
| orgId* | Name of organization whose role list is to get.
|
queryparam | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
GET http://<IP>:<Port>/intellicus/rest/role?orgId=TestOrg
API Result with XML/JSON containing list of roles for the given organization Id.
getRoleObject
This API is used to get the object of user present in the Intellicus repository.
Pattern
/rest/role/{roleId}
Method
GET
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header
|
None |
| roleId* | The ID of the role whose object we want to get. | Path | None |
| orgId* | The ID of the organization whose object role’s we want to get. | QueryParam | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
GET http://<IP>:<Port>/intellicus/rest/role/Role1?orgId=TestOrg
API Result with Status #SUCCEEDED, if request was successful. API Result with Status #FAILED, if request had failed.
createRole
This API is required to add new role in the Intellicus repository.
Pattern
/rest/role
Method
POST
Parameters
| Name | Description | Type | Default |
| sessionid * | The sessionid in which user is working
|
Request header | None |
| roleId* | Id of role you want to create. | formdata | None |
| orgId* | Name of the organization in which you want to add role. | formdata | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
POST http://<IP>:<Port>/intellicus/rest/role
Post Paramters
- roleId:RoleTest
- orgId: TestOrg
API Result with Status #SUCCEEDED, if request was successful. API Result with Status #FAILED, if request has failed.
deleteRole
This API is used to delete an existing role from the Intellicus repository.
Pattern
/rest/role/{roleId}
Method
DELETE
Parameters
| Name | Description | Type | Default |
| sessionid* | The sessionid in which user is working | Request header
|
None |
| roleId* | The ID of the role which is to be deleted. | Path | None |
| orgId* | The ID of the organization in which the role to be deleted is present. | Queryparam | None |
| Accept* | Type of the response either JSON or XML.
(Application/xml or Application/Json) |
Request header
|
XML |
Example:
DELETE http://<IP>:<Port>/intellicus/rest/role/Role1?orgId=TestOrg
API Result with Status #SUCCEEDED, if request was successful. API Result with Status #FAILED, if request had failed.