API GuidePublished Date: 24/08/2018Published Version: 2018.2
Semantify 2018. Proprietary & Confidential.
Table of ContentsDOCUMENT HISTORY..................................................................................................................................III
OVERVIEW.....................................................................................................................................................- 4 -INTRODUCTION....................................................................................................................................................................... - 4 -
PREREQUISITES........................................................................................................................................- 5 -
AUTHENTICATION....................................................................................................................................- 6 -
UNSTRUCTURED SEARCH.................................................................................................................- 9 -SUBSEQUENT PAGES...................................................................................................................................................... - 12 -CONTENT DETAILS............................................................................................................................................................ - 14 -UPDATE SYSTEM CONFIGURATION....................................................................................................................... - 15 -LOAD SOURCE CONTENT............................................................................................................................................. - 17 -FILE UPLOAD........................................................................................................................................................................ - 19 -SEMANTIFY CONTENT.................................................................................................................................................... - 22 -GET OPERATION STATUS............................................................................................................................................ - 24 -GET STRUCTURED DATA MAPPING...................................................................................................................... - 27 -UPDATE EXTERNAL KNOWLEDGE.......................................................................................................................... - 29 -GET SEMANTIFIED CONTENT..................................................................................................................................... - 31 -GET CONTENT KNOWLEDGE..................................................................................................................................... - 32 -GET CONCEPTS................................................................................................................................................................. - 34 -GET CONTENT MAPPING INFO................................................................................................................................. - 37 -
STRUCTURED SEARCH......................................................................................................................- 41 -GET APP DATA................................................................................................................................................................... - 44 -
STATUS CODES......................................................................................................................................- 47 -HTTP RESPONSE CODES............................................................................................................................................ - 47 -
CONVENTIONS.........................................................................................................................................- 48 -
UTILITY SOFTWARE.............................................................................................................................- 49 -
Semantify 2018. Proprietary & Confidential.
Document HistoryVersion No Summary of changes Modified By Date
0.1 Initial draft for Unstructured API Gopal G 07-Apr-
2017
0.2 Incorporated Structured API Shanmukha B 19-Apr-2017
0.3Incorporated Unstructured APIs load Source Content, semantify Content, operation Status
Shanmukha B 21-Apr-2017
0.4 Incorporated Unstructured API upload File Siddharth S 20-Jun-
2017
0.5 Incorporated Unstructured API get Semantified Content Siddharth S 3-Aug-2017
0.6Updated Unstructured API upload File. Incorporated API update System Configuration
Siddharth S 22-Aug-2017
0.7Updated Unstructured API upload File to include the optional override Content flag details
Siddharth S 25-Sep-2017
0.8 Incorporated Unstructured API get Semantified Content Siddharth S 30-Nov-
2017
0.9 Formatted and Edited the whole content Asad 07-Dec-
2017
1.0 Updated Unstructured API – Get Content Knowledge Asad 21-Dec-
2017
1.1 Updated Unstructured API – Get Content Mapping Info Asad 30-Jan-
2017
Semantify 2018. Proprietary & Confidential.
OverviewThis guide provides instructions for developers needing to incorporate Semantify features and functionalities into their Applications by invoking the Semantify service. This service is made available via a REST interface which can be invoked via a POST request through any HTTP client mechanism.
IntroductionEndpoint URL
The Semantify API is built on REST principles. Authenticated users can interact with any of our URIs by using the specified HTTP request method. We recommend using SSL encryption by issuing requests through HTTPS, however it’s not enforced.
Authentication
With an API, using sessions to keep track of users is not necessarily the best approach. Sometimes, your users may want to access the API directly, other times the user may want to authorize another application to access the API on their behalf.
The solution to this is to use token based authentication. The user logs in with their username and password and the application responds with a unique token that the user can use for future requests.
To ensure only authorized applications can access the API, you must authenticate your application with the API before using any features. Authentication is performed by invoking the authentication service. A successful call to this service returns an authentication token which must be used in all subsequent calls to the API.
Note: Conventions and status codes are detailed at the end of this document, please refer to those sections for better clarity on this API documentation.
Semantify 2018. Proprietary & Confidential.
PrerequisitesBefore you start using Semantify API with your application, you need to do the following:
Ensure you can access REST endpoints provided by Semantify through suitable client side libraries providing this functionality in your application. All development languages and environments should provide support for this.
Authenticate with the Semantify API in every session and use the provided token in all subsequent calls.
Handle any exceptions and error codes returned by the API as described in the latter sections of this document.
Ensure your client application is designed to :o Capture and/or generate appropriate input parameters from user input to
construct a complete Semantify API request by converting to the required input parameters.
o Handle a design pattern where a request for execution is separate from a call to retrieve details when the request has been successfully executed.
o Convert the information returned by Semantify in the details payload into the suitable user interface display in your application by reading the JSON packet sent back.
Semantify 2018. Proprietary & Confidential. 5
AuthenticationIn order to utilize any API exposed by Semantify, client needs to get authenticated before accessing any other business methods. An authentication token be returned on authentication request and the same needs to be sent on every subsequent API access.
Term Description
Prerequisite Client ID and Client Secret Key are two string values which are required to be sent in authentication request along with the username and password in order for the client to get an authentication token which should be used in sub-sequent API calls. These two string values be provided to client by Semantify during the engagement with Semantify. These two values are very important and always be kept confidential.
URL /oauth/token?grant_type=password
Method GETURL Parameters
Requiredclient_id=[string] (provided by Semantify)client_secret=[string] (provided by Semantify)username=[string] (client username, provided/created by Semantify)password=[string] (client password, provided by Semantify, managed by client)
OptionalNONE (all the parameters are required)
Header Parameters
NONE
Data Parameters
NONE
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9876/execueWSWebApp/oauth/token?grant_type=password&client_id=SEMANTIFY&client_secret=23GJHADS57RWQEMC79WER234&username=userSem&password=semPasswd
Notes: Authentication mechanism utilized here is based oauth2 specification and further details can be found at https://oauth.net/2/
Success Response
String value against “value” should be considered as auth_token which needs to be passed in all sub-sequent API calls.
Semantify 2018. Proprietary & Confidential. 6
Term Description
Status Code: 200 Success
{ "value" : "8d95d6d5-1427-47e3-8bb7-8e157aa9271e", "expiration" : 1474366252845, "tokenType" : "bearer", "refreshToken" : { "value" : "b8becf25-4e7d-4c60-816a-199e67e38e11", "expiration" : 1474366252844 }, "scope" : [ ], "additionalInformation" : { }, "expired" : false, "expiresIn" : 1799}
Error Response
Status Code: 400 Bad Request401 Unauthorized
{ "cause" : { "cause" : null, "stackTrace" : [ { "methodName" : "credentialsNotFound", "fileName" : "AbstractSecurityInterceptor.java", "lineNumber" : 339, "className" : "org.springframework.security.access.intercept.AbstractSecurityInterceptor", "nativeMethod" : false }], "additionalInformation" : null, "oauth2ErrorCode" : "unauthorized", "httpErrorCode" : 401, "summary" : "error=\"unauthorized\", error_description=\"An Authentication object was not found in the SecurityContext\"",
Semantify 2018. Proprietary & Confidential. 7
Term Description
"message" : "An Authentication object was not found in the SecurityContext", "localizedMessage" : "An Authentication object was not found in the SecurityContext"}
Semantify 2018. Proprietary & Confidential. 8
Unstructured SearchThis API provides unstructured results for search query string within the scope of the application provided. The response includes a request id, which can be used to get subsequent pages of the same search result.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /app/uss/find
Method POST
URL Parameters
NONE
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
JSON object { "appId": application identifier, "searchString": search query text}Refer Notes section, for detail explanation on this JSON request object.Sample Request:{ "appId":120, "searchString":”Net Asset Value”}
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9876/execueWSWebApp/app/uss/findNotes: JSON request object:
“appId”: This key is mandatory. The API returns the results for searchString provided within the scope of this application. For ex: “appId”: 120
“searchString”: This key is mandatory. The API finds and returns the results for this search string with in the provided appId value. For e.g: “searchString":”Net Asset Value”
Semantify 2018. Proprietary & Confidential. 9
Term Description
JSON response object:“result”: This object contains the information about the data that
is return for the request came and also the pageInfo which explains which page of the result is returned.
“pageInfo”: This object explains the current page that this response is composed with
“grid”: This object is a wrapper of meta and data of the result data
“meta”: Explains the columns of the grid“data”: Data w.r.t the columns from meta object
Success Response
Status Code: 200 Success
{ "status": "OK", "message": "Search request completed successfully", "result": { "appId": 119, "requestId": 1095927544, "resultCount": 6, "pageInfo": { "pageSize": 20, "requestedPage": 1, "totalPages": 1, "totalResults": 6 }, "grid": { "data": [ [ "3", "AIMCO CDO-144A-SUB 3M LIBOR 285BP 14-20.07.26", "US00900AAC27", "01.10.2015", "03764HAG", "AIMCO CDO144ASUB 3M LIBOR 285BP 14200726", "96", "Mar 31 2017", "100" ], [ "1", "ARES X CLO LTD-144A-SUB 3M LIBOR 280BP 14-17.04.26 AT 98.565", "US04014WAE57", "30.09.2015", "05363UAJ2", "ARES X CLO LTD144ASUB 3M LIBOR 280BP 14170426 AT 98565", "96.88", "Mar 31 2017", "100"
Semantify 2018. Proprietary & Confidential. 10
Term Description
], ... and so on till page size ], "meta": [ { "name": "contentId", "total": "N", "align": "L", "showSearch": "Y" }, { "name": "ContentTitle", "total": "N", "align": "L", "showSearch": "Y" }, ... and so on for all the columns of this grid ] } }}
Error Response
Status Code:400 Bad Request500 Internal Server Error
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 11
Subsequent PagesThis API is for obtaining the subsequent pages of the search result from the previous API (Unstructured Search). If the value of pageInfo object’s totalPages attribute in the search response is more than 1, that indicates there are more results exists than what was returned. In such cases to obtain further results requestId from previous API response and required page number to be provided in this API.
To get the subsequent pages, use the value of the requestId from the previous search API response.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /app/uss/find
Method POST
URL Parameters
NONE
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
JSON object { "appId": application identifier, "requestId": reference id to the previous search result, "pageInfo": { page object, for required page information "requestedPage": required page number }}Refer Notes section, for detail explanation on this JSON request object.
Sample Request:{ "appId": 120, "requestId": 391272844, "pageInfo": { "requestedPage": 3 }}
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9876/execueWSWebApp/app/uss/find
Semantify 2018. Proprietary & Confidential. 12
Term Description
Notes: JSON request object:
“appId”: This key is mandatory. The API returns the results for searchString provided within the scope of this application. For ex: “appId”: 120
“requestid”: This key is mandatory. Value for this key should be taken from the response of previous API call. For ex: “requestId”: 100115478
“pageInfo”: object to wrap required page request information“pageSize”: This key is optional. If provided, mentioned number of results w.r.t requested page number be returned.
For e.x: “pageSize":4
“requestedPage”: This key is mandatory. Indicated the page that needs to be returned from the available results in the scope of the search request.
For e.x: “requestedPage":2
Error Response
Status Code:400 Bad Request500 Internal Server Error
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 13
Content DetailsThis API provides the content details w.r.t any result item produced in the search request response. On every result item of the search result, an identifier pointing to the source content out of which the result item is produced be provided. That content identifier needs to be passed in along with the application identifier to fetch the content details.
Term Description
URL /app/uss/contentDesc
Method POST
URL Parameters
NONE
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
JSON object {
"appId": application identifier,"contentId": content description
}
Sample Request:{
"appId":120,"contentId":37
}Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9876/execueWSWebApp/app/uss/contentDesc
Success Response
Status Code: 200 Success{ "status": "OK", "message": "Search request completed successfully", "result": { "appId": 120, "contentId": 37, "description": "ARES X CLO LTD-144A-SUB 3M LIBOR 280BP 14-17.04.26 AT 98.565" }}
Error Response
Status Code:
Semantify 2018. Proprietary & Confidential. 14
Term Description
400 Bad Request500 Internal Server Error
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Update System ConfigurationThis API provides a service to synchronize the batch application with the main web application before files can be uploaded. This update is required after the application has been built on the main application side.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /app/uss/updateSystemConfiguration
Method POST
URL Parameters
NONE
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
NONE
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9876/execueWSWebApp/app/uss/updateSystemConfiguration Notes: No parameter has to be passed in the URL, or the body of the API message.
Success Response
Status Code: 200 Success
Semantify 2018. Proprietary & Confidential. 15
Term Description
{ "status": "OK", "message": " Success"}
Error Response
Status Code:400 Bad Request500 Internal Server Error
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 16
Load Source ContentThis API provides a service to load the unstructured source content which can be later pushed to semantification process.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /app/uss/loadSourceContent
Method POST
URL Parameters
NONE
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
JSON object {"content": The source text/article to be loaded (String),"appId": Application ID (Long),"url": The external/internal url (String),"title": Title of the source content (String) }Refer Notes section, for detail explanation on this JSON request object.Sample Request:{"appId":120,"content":" ARES X CLO LTD-144A-SUB 3M LIBOR 280BP 14-17.04.26 AT 98.565"}
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9876/execueWSWebApp/app/uss/ loadSourceContent Notes: JSON request object:
“appId”: This key is mandatory. The API returns the results for searchString provided within the scope of this application. For ex: “appId”: 120
“content”: This key is mandatory. It holds the actual text from the unstructured source. "url": Optional key. The external/internal url.
Semantify 2018. Proprietary & Confidential. 17
Term Description
"title": Optional key. Title of the source content.JSON response object:“sourceContentId”: Identifier for the newly loaded source content. (Long data type)
Success Response
Status Code: 200 Success
{ "status": "OK", "message": "Success", "result": { "sourceContentId": 308 }}
Error Response
Status Code:400 Bad Request500 Internal Server Error
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 18
File UploadThis API provides a service to load the source content from documents that are saved as PDF/Word files which can be later pushed for semantification.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /app/uss/uploadFile
Method POST
URL Parameters
RequiredfileURL=[string] (value will be the URL of the file for upload)uploadAsCompressedFile=[string](value can be either ‘Y’ in case of archived ZIP file, or else ‘N’)appId=[string] (Application id of the unstructured app for which the content is being loaded)
OptionalfileType=[string] (value will be ‘PDF’ for uploading PDF type document and ‘WORD’ for word type documents (Non - OCR))overrideContent=[string] (default value = ‘false’. In case override of a file is required, then this value to be set as ‘true’)fileId=[string] (If ‘overrideContent=true’ param has been set, then the file id of the file whose content is to be overridden)
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
NONE
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:8095/execueWSWebApp/app/uss/uploadFile?fileType=PDF&fileURL=fileLocation&uploadAsCompressedFile=N&appId=110&overrideContent=true&fileId=1396
Notes: URL Parameters:
“appId”: This key is mandatory. It is the application id of the unstructured app for which the content is being loaded.For ex: appId=110
“fileType”: This key is mandatory. It is the type of source content file. In
Semantify 2018. Proprietary & Confidential. 19
Term Description
case of PDF format, the fileType will be ‘PDF’ For ex: fileType=PDF
"fileURL": This key is mandatory. The URL of the file location
"uploadAsCompressedFile": This key is mandatory. Its value may by ‘Y’ in case the uploaded source content is in an archive ZIP file. Else its value has to be provided as ‘N’.For ex: uploadAsCompressedFile=N
“overrideContent”: This key is optional. Default value is ‘false’. Other value can be ‘true’ in case the content of an already uploaded file has to be overridden.
“fileId”: This key is required only if ‘overrideContent=true’ has been set in the URL. The value will be the file id of the file that was uploaded previously, but now, whose content is to be overridden. The value for fileId is returned by the uploadFile API, whenever a file is uploaded.
JSON response object:“fileName”: File name for the newly loaded source content.
(String data type)“fileId”: Identifier for the newly loaded source content. (Long data
type)Success Response
Status Code: 200 Success
{ "status": "OK", "message": "Success", "result": { "fileName": "20170620180619904_mya_1_pdfmailer1502.pdf", "fileId": 1040 }}
Error Response
Status Code:400 Bad Request500 Internal Server Error
Semantify 2018. Proprietary & Confidential. 20
Term Description
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 21
Semantify ContentThis API invokes semantification process. Any previously loaded source content will be processed during semanfication for a particular application. The content will be processed in batches. The knowledge model association and the possibility reduction happens during this process.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /app/uss/semantifyContent
Method POST
URL Parameters
NONE
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
JSON object {"appId": Application ID (Long),"failedArticles": Optional. Whether to include previously failed articles into the current semantification process (Boolean),"autoKnowledge": Optional. Whether to consider auto knowledge or not during semantification (Boolean). Helpful in processing semi-structured data. }Refer Notes section, for detail explanation on this JSON request object.Sample Request:{"appId":120,"failedArticles":true,"autoKnowledge":false}
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9876/execueWSWebApp/app/uss/ semantifyContent Notes: JSON request object:
“appId”: This key is mandatory. The API returns the results for searchString provided within the scope of this application. For ex: “appId”: 120
"failedArticles": Optional. Whether to include previously failed articles Semantify 2018. Proprietary & Confidential. 22
Term Description
into the current semantification process (Boolean)."autoKnowledge": Optional. Whether to consider auto knowledge or not during semantification (Boolean). Helpful in processing semi-structured data
JSON response object:“jobRequestId”: Identifier for the loaded source content.
Error Response
Status Code:400 Bad Request500 Internal Server Error
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 23
Get Operation StatusAPI to view semantification status. This can be called any time during semantification process.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /app/uss/operationStatus
Method POST
URL Parameters
NONE
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
JSON object {"jobRequestId": Semantification JOB ID (Long).}Refer Notes section, for detail explanation on this JSON request object.Sample Request:{"jobRequestId":3871}
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9876/execueWSWebApp/app/uss/ operationStatus
Notes:JSON request object:
“jobRequestId”: This key is mandatory. Semantification JOB ID.
JSON response object:“jobType”: The type of the job invoked on the scheduler. The
value will be always "SEMANTIFI_CONTENT".“operationStatus”: List of operational stages during
semantification process.“operationalStage”: The batch details that is undergoing
semantification.“jobStatus”: The status of the current batch. “startDate”: The batch start date.“endDate”: The batch end date
Semantify 2018. Proprietary & Confidential. 24
Term Description
Success Response
Status Code: 200 Success
{ "status": "OK", "message": "Success", "result": { "jobType": "SEMANTIFI_CONTENT", "operationStatus": [ { "operationalStage": "Processing Batch1", "jobStatus": "SUCCESS", "startDate": "21-Apr-2017", "endDate": "21-Apr-2017" }, { "operationalStage": "Processing Batch2", "jobStatus": "SUCCESS", "startDate": "21-Apr-2017", "endDate": "21-Apr-2017" }, { "operationalStage": "Processing Batch3", "jobStatus": "SUCCESS", "startDate": "21-Apr-2017", "endDate": "21-Apr-2017" }, { "operationalStage": "Processing Batch4", "jobStatus": "SUCCESS", "startDate": "21-Apr-2017", "endDate": "21-Apr-2017" }, { "operationalStage": "Processing Batch5", "jobStatus": "SUCCESS", "startDate": "21-Apr-2017", "endDate": "21-Apr-2017" }, { "operationalStage": "No content is available for semantification", "jobStatus": "SUCCESS", "startDate": "21-Apr-2017" } ] }}
Error Status Code:
Semantify 2018. Proprietary & Confidential. 25
Term Description
Response 400 Bad Request500 Internal Server Error
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 26
Get Structured Data Mapping API to retrieve structured data mapping for an unstructured application.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL udx/features/mapping/allMethod GET
URL Parameters
RequiredappId=[string] (Application id of the unstructured app for which the structure Data Mapping is being requested)
OptionalNONE (all the parameters are required)
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)
Data Parameters
NONE
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9999/execueWSWebApp/udx/features/mapping/all?appId=161
Notes: JSON request object:
“appId”: This key is mandatory. The API returns the results for searchString provided within the scope of this application. For ex: “appId”: 232
“pageSize”: This key is optional. If provided, mentioned number of results w.r.t requested page number be returned.
For e.x: “pageSize":4
Success Response
Success ResponseStatus Code:
200 Success{ "message": "Operation completed successfully", "messages": null, "status": true, "page": { "pageSizes": [
Semantify 2018. Proprietary & Confidential. 27
Term Description
10, 20, 30 ], "enableTextbox": true, "enableSummary": true, "totalItems": 56, "pageSize": 14, "currentPage": 2, "itemsPerPage": 10, "totalPages": 6 }
}
Example 1 For example, If total items is 56 and items per page defined as 10, then the total pages would be 6. http://localhost:9999/execueWSWebApp/udx/features/mapping/all?appId=161¤tPage=2
Run the above URL to get the subsequent pages
Example 2 To retrieve the total concepts (Items) in one go, run the same query (assuming we know the total items by running the default query at first instance). And therefore, the items per page will be displayed as total number of concepts (items).http://localhost:9999/execueWSWebApp/udx/features/mapping/all?appId=161&pageSize=14
Where the pageSize(key) is optional. If provided, mentioned number of results w.r.t requested page number be returned.
For e.x: “pageSize": 14Error Response
Status Code:400 Bad Request500 Internal Server Error
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 28
Update External Knowledge API to update context specific content external knowledge for a given file.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL udx/sc/updateExternalKnowledgeMethod PUTURL Parameters
NONE
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
JSON object { "data": { "appId": 141, "fileId": "8756", "externalKnowledge": "<DocMemberName>Allegis from API</DocMemberName><SowAmount>2000</SowAmount>"},
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9999/execueWSWebApp/udx/sc/updateExternalKnowledge Notes: JSON request object:
“appId”: This key is mandatory. The API returns the results for searchString provided within the scope of this application. For ex: “appId”: 141
“fileId”: The ID of the file which we have been uploaded For ex: “FileId”: 8756“externalKnowledge”: The knowledge to be updated in context specific content.
For e.x: "externalKnowledge": "<DocMemberName>Allegis from API</DocMemberName><SowAmount>2000</SowAmount>"
Success Response
Status Code: 200 Success
"message": "External Knowledge updated successfully",
Semantify 2018. Proprietary & Confidential. 29
Term Description
"messages": null, "status": true, "page": null {
}
Error Response
Status Code:400 Bad Request500 Internal Server Error
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 30
Get Semantified Content API to retrieve semantified data for a file that was uploaded in an application. This can be called after the semantification process is complete.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /app/uss/getSemantifiedContent
Method POST
URL Parameters
RequiredfileId=[string] (The id of the file that was uploaded before semantification)appId=[string] (Application id of the unstructured app for which the semantified content is being requested)
OptionalNONE (all the parameters are required)
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=multipart/form-data
Data Parameters
NONE
Success Response
Success ResponseStatus Code:
200 Success{ "status": "OK", "message": "Success", "result": { "items" : [ { "values" : ["2014-11-05"], "key" : "createDate" } ]}
Error Response
Status Code:400 Bad Request500 Internal Server Error
{
"status": "ERROR",
Semantify 2018. Proprietary & Confidential. 31
Term Description
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Get Content KnowledgeThis API provides a service to get content knowledge which can be later pushed to semantification process.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL udx/sc/getContentKnowledgeMethod GET
URL Parameters
RequiredappId=[string] (Application id of the unstructured app for which the structure Data Mapping is being requested)fileId=[string] (If ‘overrideContent=true’ param has been set, then the file id of the file whose content is to be overridden)
OptionalNONE (all the parameters are required)
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
NONE
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9999/execueWSWebApp/udx/sc/getContentKnowledge?appId=123&fileId=9054
Notes: JSON request object:“appId”: This key is mandatory. The API returns the results for searchString provided within the scope of this application.
Semantify 2018. Proprietary & Confidential. 32
Term Description
For ex: “appId”: 123“fileid”: This key is optional. If provided, mentioned number of results w.r.t requested page number be returned.
For e.x: “fileId": 9054“extractedKnowledge”: This specifies Index extracted using the rule based regex extraction“externalKnowledge”: This specifies Externally updated Index values
Success Response
Status Code: 200 Success
{ success response: { "data": { "fileId": "11942", "contentKnowledge": "<extractedKnowledge> <DocumentType>CO</DocumentType> <DocMemberName>Allegis Group Inc</DocMemberName> <ChangeOrderAmount>26,720</ChangeOrderAmount> <ChangeOrderDate>7/17/2016</ChangeOrderDate> <ChangeOrderSOWTitle>AD Security and Red Forest</ChangeOrderSOWTitle> <ChangeOrderSOWReference>January 14, 2016</ChangeOrderSOWReference></extractedKnowledge><externalKnowledge> <SOWStartDate>2014-11-19</SOWStartDate> <SOWEndDate>2016-12-31</SOWEndDate> <Sowsignaturemembertitle>Test2</Sowsignaturemembertitle> <DocMemberName>Updated by Aditya S</DocMemberName> <SupplierName>Updated by AS</SupplierName> <Amount>20012</Amount> <PaymentTerm>70 Days</PaymentTerm></externalKnowledge>" }, "message": "Operation completed successfully", "messages": null, "status": true, "page": null
}
Error Response
Status Code:400 Bad Request500 Internal Server Error
{
"status": "ERROR",
Semantify 2018. Proprietary & Confidential. 33
Term Description
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Get Concepts API to retrieve concepts for an application.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /kdx/suggest/terms/concepts/
Method GET
URL Parameters
RequiredappId=[string] (Application id of the app for which the concepts are being requested)
OptionalNONE (all the parameters are required)
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:8082/execueWSWebApp/kdx/suggest/terms/concepts/111
Notes: URL Parameters:
“appId”: This key is mandatory. It is the application id of the app for which the concept is being requested.
Semantify 2018. Proprietary & Confidential. 34
Term Description
For ex: If the appId is 111, then it will directly be passed in the URL.
JSON response object: “displayName”: Name of the concept “bedId”: Concept Id “message”: Process completion status message “pageSizes”: Possible page sizes of the result "totalItems": Total concepts available "pageSize": Current page size "currentPage": Current Page number "itemsPerPage": Items per page "totalPages": Total number of pages
Success Response
Status Code: 200 Success
{"data":
[{"bedId": 10388,"displayName": "Supplier"
},{
"bedId": 10004,"displayName": "Client"
}}],
"message": "Operation completed successfully","messages": null,"status": true,"page": {
"pageSizes": [10,20,30],"enableTextbox": true,"enableSummary": true,"totalItems": 2,"pageSize": 10,"currentPage": 1,"itemsPerPage": 10,"totalPages": 1
}Example 1 For example, If total items is 60 and items per page defined as 10, then
the total pages would be 6.Example 2 To retrieve the total concepts (Items) in one go, run the same query
Semantify 2018. Proprietary & Confidential. 35
Term Description
(assuming we know the total items by running the default query at first instance). And therefore, the items per page will be displayed as total number of concepts (items).
Error Response
Status Code:400 Bad Request500 Internal Server Error
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 36
Get Content Mapping Info This API is used to retrieve all files or articles which are already semantified for a given application id.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /udx/sc/getContentMappingInfo
Method GET
URL Parameters
RequiredappId=[string] (Application id of the app for which the Content are being requested)
OptionalNONE (all the parameters are required)
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9999/execueWSWebApp/udx/sc/getContentMappingInfo?appId=234 Notes: URL Parameters:
“appId”: This key is mandatory. It is the application id of the app for which the concept is being requested.For ex: If the appId is 234, then it will directly be passed in the URL.
JSON response object: {
"id": 2316, "contentId": 2736, "sourceItemId": "3417", "title": "SolutionsIQ_SOW_2016.02.01.pdf" }, Where, "id": source content id "contentId": semantified content id"sourceItemId": file id
Semantify 2018. Proprietary & Confidential. 37
Term Description
"title": file name Success Response
{ "data": [ { "id": 2300, "contentId": 2743, "sourceItemId": "3401", "title": "Hewlett Packard Enterprise_SOW_2016.05.26.pdf" }, { "id": 2303, "contentId": 2742, "sourceItemId": "3404", "title": "Informatica Corp_SOW_2016.05.17.pdf" }, { "id": 2306, "contentId": 2741, "sourceItemId": "3407", "title": "Manhattan Telecommunications Corp aka MetTel_SOW_2016.04.11.pdf" }, { "id": 2307, "contentId": 2740, "sourceItemId": "3408", "title": "MetricStream Inc_SOW_2015.08.07.pdf" }, { "id": 2310, "contentId": 2739, "sourceItemId": "3411", "title": "Perficient Inc LLC_SOW_2016.05.31.pdf" }, { "id": 2311, "contentId": 2738, "sourceItemId": "3412", "title": "Planview Delaware LLC_SOW 2_2016.05.31.pdf" }, { "id": 2312, "contentId": 2737, "sourceItemId": "3413", "title": "Portal Solutions LLC_SOW_2016.07.25.pdf" }, {
Semantify 2018. Proprietary & Confidential. 38
Term Description
"id": 2316, "contentId": 2736, "sourceItemId": "3417", "title": "SolutionsIQ_SOW_2016.02.01.pdf" }, { "id": 2321, "contentId": 2735, "sourceItemId": "3422", "title": "The Verndale Corporation_SOW_2016.07.06.pdf" }, { "id": 2322, "contentId": 2734, "sourceItemId": "3423", "title": "TIBCO Software Inc_SOW_2013.12.09.pdf" } ], "message": "Operation completed successfully", "messages": null, "status": true, "page": { "pageSizes": [ 10, 20, 30 ], "enableTextbox": true, "enableSummary": true, "totalItems": 30, "pageSize": 10, "currentPage": 1, "itemsPerPage": 10, "totalPages": 3 }}
Example 1 For example, If total items is 60 and items per page defined as 10, then the total pages would be 6.
Example 2 To retrieve the total files in one go, run the same query (assuming we know the total files by running the default query at first instance). And therefore, the items per page will be displayed as total number of files.
Error Response
Status Code:400 Bad Request500 Internal Server Error
{
Semantify 2018. Proprietary & Confidential. 39
Term Description
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 40
Structured SearchThis API provides structured results for search query string within the scope of the application provided. The successful response includes one or more assets results. Each result describes how the search string has resulted into a pseudo statement and to the actual sql statement (review query). In addition to this, the result also tells whether there is data present or not, matching relevance and a query id which can be used to retrieve the actual data. Please refer section Structured – Get App Data to retrieve actual data.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /app/find
Method POST
URL Parameters
NONE
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
JSON object { "appId": application identifier, "searchString": search query text}Refer Notes section, for detail explanation on this JSON request object.Sample Request:{ "appId":120, "searchString":”Average bill rate by business unit and supplier”}
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9876/execueWSWebApp/app/find
Notes: JSON request object:
“appId”: This key is mandatory. The API returns the results for searchString provided within the scope of this application. For ex: “appId”: 113
Semantify 2018. Proprietary & Confidential. 41
Term Description
“searchString”: This key is mandatory. The API finds and returns the results for this search string with in the provided appId value. For e.g: “searchString":”Average bill rate by business unit and supplier”
JSON response object:“result”: This list of object contains the information about the
data that is returned for the request.“appId”: The application id “dataPresent”: [true/false] Whether the data present or not.
Useful whether to go for subsequent request in order get data.“queryId”: Helps in retrieving data. Used as an input parameter
for /app/data service“appName”: Application name“appType”: Whether the result belongs to structured or
unstructured application“relevance”: Match percentage “reviewQuery”: Generated SQL query to fetch the data.“pseudoStatement”: English representation of the user question.“reportHeader”: English representation of the report.
Success Response
Status Code: 200 Success
{ "status": "OK", "message": "Success", "result": [ { "appId": 113, "dataPresent": true, "queryId": 3216, "appName": "SOW Analytics POC VMS Data", "appType": "Structured", "relevance": 99.38, "reviewQuery": "SELECT AVG(ZYJ17.`Bill Rate`) AS ZVO03, SSK19.`Business Unit` AS AMN31, ERF97.`Supplier Name` AS HHP86 FROM `sow_ids` YYH05 INNER JOIN `statement of work` SSK19 ON YYH05.`sow id`=SSK19.`SOW ID` INNER JOIN `sow line item` ERF97 ON YYH05.`sow id`=ERF97.`SOW ID` INNER JOIN `sow work order` ZYJ17 ON YYH05.`sow id`=ZYJ17.`SOW ID` GROUP BY ERF97.`Supplier Name`, SSK19.`Business Unit` ORDER BY ERF97.`Supplier Name` ASC, SSK19.`Business Unit` ASC", "pseudoStatement": "Average of Bill Rate summarized by Supplier, Business Unit ordered by Supplier, Business Unit", "reportHeader": "Bill Rate by Supplier, Business Unit"
Semantify 2018. Proprietary & Confidential. 42
Term Description
} ]}
Error Response
Status Code:400 Bad Request500 Internal Server Error
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 43
Get App Data This API helps in retrieving data table for a given queryId.
Term Description
Prerequisite Authorization should be done and auth_token be acquired prior to using this API.
URL /app/data
Method POST
URL Parameters
NONE
Header Parameters
Authorization=Bearer [string] (auth_token acquired during authentication call)Content-Type=application/json
Data Parameters
JSON object {"queryId": query id from /app/find response}Refer Notes section, for detail explanation on this JSON request object.Sample Request:{"queryId":3216}
Sample URL
Values used in this sample are for demonstration purposes only.http://localhost:9876/execueWSWebApp/app/ data
Notes: JSON request object:
“queryId”: This key is mandatory. This value is taken from previous search result. For ex: “appId”: 113
JSON response object:“result”: This object contains the information about the data that
is return for the request.“data”: Data with respect to the columns from meta object “meta”: Explains the columns of the grid
Success Response
Status Code: 200 Success
{ "status": "OK",
Semantify 2018. Proprietary & Confidential. 44
Term Description
"message": "Success", "result": { "data": [ [ "118.15", "General & Accounting", "3Key Consulting, Inc." ], [ "59.75", "Global Commercial Operations", "3Key Consulting, Inc." ], .. and so on till page size ], "meta": [ { "name": "Avg Bill Rate ($)", "total": "N", "align": "R", "showSearch": "N", "multiSelect": "N", "columnTotal": null, "multiSelectData": [] }, { "name": "Business Unit", "total": "N", "align": "L", "showSearch": "Y", "multiSelect": "N", "columnTotal": null, "multiSelectData": [] }, { "name": "Supplier", "total": "N", "align": "L", "showSearch": "Y", "multiSelect": "N", "columnTotal": null, "multiSelectData": [] } ] }}
Error Response
Status Code:400 Bad Request500 Internal Server Error
Semantify 2018. Proprietary & Confidential. 45
Term Description
{
"status": "ERROR",
"message": "Request failed during processing",
"error": {
"type": "SYSTEM_ERROR",
"details": [
"[90000] Unable to process the request"
]
}
Semantify 2018. Proprietary & Confidential. 46
Status CodesAll status codes are standard HTTP status codes. The below ones are used in this API.
2XX – Success
3XX - Redirect
4XX - Error occurred in client’s part (User Error)
5XX - Error occurred in server’s part (Server Error)
HTTP response codesResponse code Description200 — Success Everything went smooth.401 — Unauthorized Missing or incorrect API token in header.422 — Not process able Entity Something with the message isn’t quite right, this could be malformed JSON or incorrect fields. In this case, the response body contains JSON {Error Code: 405, Message: "details"} with an API error code and message containing details on what went wrong.500 — Internal Server Error This is an issue with Semantify servers processing your request. In most cases the message is lost during the process, and we are notified so that we can investigate the issue.503 — Service Unavailable During planned service outages, Semantify API services will return this HTTP response and associated JSON body.
Semantify 2018. Proprietary & Confidential. 47
ConventionsClient - Client application.
Status - HTTP status code of response.
All the possible responses are listed under ‘Responses’ for each method. Only one of them is issued per request from server.
All responses are in JSON format.
All request parameters are mandatory unless explicitly marked as [optional]
The type of values accepted for a request parameter are shown the values column like this [10|<any number>] .The | symbol means OR. If the parameter is [optional], the default value is shown in blue bold text, as 10 is written in [10|<any number>].
Semantify 2018. Proprietary & Confidential. 48
Utility SoftwareStandalone REST Client Software
Semantify suggests to use REST Client from WizTools for API testing purposes, clients are free to choose any other client based on their comfort.
Suggested client can be found at https://github.com/wiztools/rest-client
Browser Plugin based REST Client
Semantify suggests to use Advanced REST Client from Chrome Store or any other plugin as per the comfort of Client for API testing purposes. Suggested plugin can be found at https://advancedrestclient.com/
Semantify 2018. Proprietary & Confidential. 49