API Guide · 2 days ago · Semantify Proprietary & Confidential - 2 Table of Contents OVERVIEW ..... - 4 - CONVENTIONS..... - 4 - CURRENT VERSION..... - 4 -

API Guide Published Date: 24/08/2018

Release Version: 2019.1

Semantify Proprietary & Confidential

- 2 -

Table of Contents OVERVIEW ................................................................................................................. - 4 -

CONVENTIONS............................................................................................................ - 4 - CURRENT VERSION .................................................................................................... - 4 - SCHEMA .................................................................................................................... - 4 - HTTP REDIRECTS ...................................................................................................... - 4 - HTTP REQUESTS ....................................................................................................... - 5 - HTTP METHODS ........................................................................................................ - 5 - AUTHENTICATION ....................................................................................................... - 5 - PAGINATION ............................................................................................................... - 6 - URL FORMAT ............................................................................................................ - 6 -

API REFERENCE DOCUMENTATION ...................................................................... - 7 - OVERVIEW ................................................................................................................. - 7 - RESOURCE INFORMATION ........................................................................................... - 7 - ENDPOINTS AND METHODS.......................................................................................... - 7 - PARAMETERS ............................................................................................................. - 7 - REQUEST ................................................................................................................... - 7 - RESPONSE EXAMPLE AND SCHEMA .............................................................................. - 8 -

UNSTRUCTURED ...................................................................................................... - 9 - UNSTRUCTURED SEARCH ............................................................................................ - 9 - SUBSEQUENT PAGES ................................................................................................ - 12 - CONTENT DETAILS ................................................................................................... - 14 - UPDATE SYSTEM CONFIGURATION ............................................................................. - 16 - LOAD SOURCE CONTENT .......................................................................................... - 18 - FILE UPLOAD ........................................................................................................... - 20 - SEMANTIFY CONTENT ............................................................................................... - 23 - GET OPERATION STATUS .......................................................................................... - 25 - GET STRUCTURED DATA MAPPING ............................................................................ - 28 - UPDATE EXTERNAL KNOWLEDGE ............................................................................... - 30 - GET SEMANTIFIED CONTENT ..................................................................................... - 31 - GET CONTENT KNOWLEDGE ...................................................................................... - 33 - GET CONCEPTS ....................................................................................................... - 35 - GET CONTENT MAPPING INFO ................................................................................... - 38 -

STRUCTURED SEARCH ......................................................................................... - 42 - GET APP DATA ......................................................................................................... - 45 -

QUERY PARAMETERS ........................................................................................... - 48 -

STATUS CODES ...................................................................................................... - 49 - HTTP RESPONSE CODES .......................................................................................... - 49 -


- 3 -

UTILITY SOFTWARE .................................................................................................. - 50 -


- 4 -

Overview Conventions Client - Client application.

Status - HTTP status code of the response.

All the possible responses are listed under ‘Responses’ for each method. Only one of them is issued per request from the 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 is 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>].

Current Version APIs only need to be up-versioned when a breaking change is made. Breaking changes include:

A change in the format of the response data for one or more calls

A change in the response type (i.e., changing an integer to a float)

Remove any part of the API.

Schema A schema is a metadata that tells us how our data is structured. Most databases implement some form of the schema which enables us to reason about our data in a more structured manner. The Semantify REST API utilizes JSON Schema to handle the structuring of its data.

HTTP Redirects URL redirection, also known as URL forwarding, is a technique to give a page, a form or a whole Web application, more than one URL address. HTTP provides a special kind of responses, HTTP redirects, to perform this operation used for many goals: temporary redirection while site maintenance is ongoing, permanent redirection to keep external links working after a change of the site's architecture, progress pages when uploading a file, and so on.


- 5 -

HTTP Requests Example request URIs

HTTP GET http://www.appdomain.com/users

HTTP GET http://www.appdomain.com/users?size=20&page=5

HTTP GET http://www.appdomain.com/users/123

HTTP GET http://www.appdomain.com/users/123/address

HTTP POST http://www.appdomain.com/users

HTTP POST http://www.appdomain.com/users/123/accounts

HTTP PUT http://www.appdomain.com/users/123

HTTP PUT http://www.appdomain.com/users/123/accounts/456

HTTP DELETE http://www.appdomain.com/users/123

HTTP DELETE http://www.appdomain.com/users/123/accounts/456

HTTP Methods RESTful APIs enable you to develop any web application having all possible CRUD (create, retrieve, update, delete) operations. REST guidelines suggest using a specific HTTP method on a specific type of call made to the server.

HTTP GET

HTTP POST

HTTP PUT

HTTP DELETE

HTTP PATCH

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.


- 6 -

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.

Pagination Most endpoints that return a list of entities will need to have some pagination. Without pagination, a simple search could return millions or even billions of hits causing extraneous network traffic. Paging requires an implied ordering. By default, this may be the item’s unique identifier but can be other ordered fields such as a created date.

URL Format When you try to access a webpage on the internet, the web address you put into the browser has a specific format. In its entirety (including the http:// part), this web address is known as a URL.


- 7 -

API Reference Documentation Overview This 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.

Resource Information "Resources" refers to the information returned by an API. Most APIs have various categories of information or various resources, that can be returned. The resource description provides details about the information returned in each resource.

Endpoints and Methods The endpoints indicate how you access the resource, and the method used with the endpoint indicates the allowed interactions (such as GET, POST, or DELETE) with the resource. The endpoint shows the end path of a resource URL only, not the base path common to all endpoints. The same resource usually has a variety of related endpoints, each with different paths and methods but returning variant information about the same resource. Endpoints usually have brief descriptions similar to the overall resource description but shorter.

Parameters Parameters are options you can pass with the endpoint (such as specifying the response format or the amount returned) to influence the response. There are four types of parameters: header parameters, path parameters, query string parameters, and request body parameters. The different types of parameters are often documented in separate groups. Not all endpoints contain each type of parameter.

Request The request example includes a sample request using the endpoint, showing some parameters configured. The request example usually doesn’t show all possible parameter configurations, but it should be as productive as possible with parameters. Sample requests sometimes include code snippets that show the same request in a variety of languages


- 8 -

Response Example and Schema The response example shows a sample response from the request example. The response example is not comprehensive of all parameter configurations or operations, but it should correspond with the parameters passed in the request example. The response lets developers know if the resource contains the information they want, the format, and how that information is structured and labeled. The description of the response is known as the response schema. The response schema documents the response in a more comprehensive, general way, listing each property returned, what each property contains, and the data format of the values, the structure, and other details.


- 9 -

Unstructured Unstructured Search This 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/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”: 120

http://localhost:9876/execueWSWebApp/app/uss/find


- 10 -

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":”Net Asset Value” 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",


- 11 -

Term Description

"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"

],

... and so on till page size

],

"meta": [

{

"name": "contentId",

"total": "N",

"align": "L",

"showSearch": "Y"

},

{


- 12 -

Term Description

"name": "ContentTitle",

"total": "N",

"align": "L",

"showSearch": "Y"

},

... and so on for all the columns of this grid

]

}

}

}

Error Response

Status Code:

400 Bad Request 500 Internal Server Error

{

"status": "ERROR",

"message": "Request failed during processing",

"error": {

"type": "SYSTEM_ERROR",

"details": [

"[90000] Unable to process the request"

]

}

Subsequent Pages This 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. 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.


- 13 -

Term Description

Prerequisite

Authorization should be done, and auth_token be acquired before using this API.

URL /app/uss/find Method POST URL Parameters

NONE

Header Parameters


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 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.



- 14 -

Term Description

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 Request 500 Internal Server Error

{

"status": "ERROR", "message": "Request failed during processing",

"error": {

"type": "SYSTEM_ERROR", "details": [


] }

Content Details This 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


- 15 -

Term Description

Header Parameters


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


{


"error": {



] }

http://localhost:9876/execueWSWebApp/app/uss/contentDesc


- 16 -

Update System Configuration This 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 primary application side.

Term Description

Prerequisite


URL /app/uss/updateSystemConfiguration Method POST URL Parameters

NONE

Header Parameters


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": "OK", "message": " Success" }

Error Response


{ "status": "ERROR",


"error": { "type": "SYSTEM_ERROR",

"details": [


http://localhost:9876/execueWSWebApp/app/uss/updateSystemConfiguration


- 17 -

Term Description

]

}


- 18 -

Load Source Content This API provides a service to load the unstructured source content which can be later pushed to semantification process.

Term Description

Prerequisite


URL /app/uss/loadSourceContent

Method POST URL Parameters

NONE

Header Parameters


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. "title": Optional key. Title of the source content. JSON response object:



- 19 -

Term Description

“sourceContentId”: Identifier for the newly loaded source content. (Long data type)

Success Response


{ "status": "OK", "message": "Success", "result": { "sourceContentId": 308 } }

Error Response


{

"status": "ERROR",

"message": "Request failed during processing", "error": {


"details": [ "[90000] Unable to process the request"

]

}


- 20 -

File Upload This 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


URL /app/uss/uploadFile Method POST

URL Parameters

Required fileURL=[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)

Optional fileType=[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


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 the case of PDF format, the fileType will be ‘PDF.’


- 21 -

Term Description

For ex: fileType=PDF "file URL": This key is mandatory. The URL of the file location "uploadAsCompressedFile": This key is mandatory. Its value may vary 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. The 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 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": "OK", "message": "Success", "result": { "fileName": "20170620180619904_mya_1_pdfmailer1502.pdf", "fileId": 1040 } }

Error Response


{


- 22 -

Term Description

"status": "ERROR",



"details": [

"[90000] Unable to process the request" ]

}


- 23 -

Semantify Content This API invokes the 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


URL /app/uss/semantifyContent Method POST URL Parameters

NONE

Header Parameters


Data Parameters

JSON object { "appId": Application ID (Long), "failedArticles": Optional. Whether to include previously failed articles into the current semantification process (Boolean), "autoKnowledge": Optional. Either 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



- 24 -

Term Description

"failedArticles": Optional. Whether to include previously failed articles into the current semantification process (Boolean). "autoKnowledge": Optional. Either 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": "ERROR",




]

}


- 25 -

Get Operation Status API to view semantification status. It can be called any time during the semantification process.

Term Description

Prerequisite


URL /app/uss/operationStatus Method POST URL Parameters

NONE

Header Parameters


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 always be "SEMANTIFI_CONTENT." “operationStatus”: List of operational stages during the semantification process. “operational stage”: The batch details that is undergoing semantification. “jobStatus”: The status of the current batch. “startDate”: The batch start date. “endDate”: The batch end date



- 26 -

Term Description

Success Response


{ "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" } ] } }


- 27 -

Term Description

Error Response


{


"error": {



] }


- 28 -

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 before using this API.

URL udx/features/mapping/all Method GET

URL Parameters

Required appId=[string] (Application id of the unstructured app for which the structure Data Mapping is being requested) Optional

NONE (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/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 Response Status Code:

200 Success { "message": "Operation completed successfully", "messages": null, "status": true, "page": { "pageSizes": [ 10,

http://localhost:9999/execueWSWebApp/udx/features/mapping/all?appId=161


- 29 -

Term Description

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&currentPage=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": 14

Error Response


{

"status": "ERROR",




]

}

http://localhost:9999/execueWSWebApp/udx/features/mapping/all?appId=161&currentPage=2

http://localhost:9999/execueWSWebApp/udx/features/mapping/all?appId=161&currentPage=2

http://localhost:9999/execueWSWebApp/udx/features/mapping/all?appId=161&pageSize=14

http://localhost:9999/execueWSWebApp/udx/features/mapping/all?appId=161&pageSize=14


- 30 -

Update External Knowledge API to update context specific content external knowledge for a given file.

Term Description

Prerequisite


URL udx/sc/updateExternalKnowledge Method PUT URL Parameters NONE

Header Parameters


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 “external knowledge”: The knowledge to be updated in context specific content.

For e.x: "externalKnowledge": "<DocMemberName>Allegis from API</DocMemberName><SowAmount>2000</SowAmount>"

Success Response


"message": "External Knowledge updated successfully", "messages": null,

http://localhost:9999/execueWSWebApp/udx/sc/updateExternalKnowledge


- 31 -

Term Description

"status": true, "page": null {

}

Error Response


{

"status": "ERROR",




]

}

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


URL /app/uss/getSemantifiedContent Method POST

URL Parameters

Required fileId=[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)

Optional NONE (all the parameters are required)

Header Parameters

Authorization=Bearer [string] (auth_token acquired during authentication call) Content-Type=multipart/form-data



- 32 -

Term Description

Success Response

Success Response Status Code:

200 Success { "status": "OK", "message": "Success", "result": { "items" : [ { "values" : ["2014-11-05"], "key" : "createDate" } ] }

Error Response


{ "status": "ERROR",



"details": [

"[90000] Unable to process the request" ]

}


- 33 -

Get Content Knowledge This API provides a service to get content knowledge which can be later pushed to semantification process.

Term Description

Prerequisite


URL udx/sc/getContentKnowledge Method GET

URL Parameters

Required appId=[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)


Header Parameters



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. 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


{ success response: { "data": {

http://localhost:9999/execueWSWebApp/udx/sc/getContentKnowledge?appId=123&fileId=9054

http://localhost:9999/execueWSWebApp/udx/sc/getContentKnowledge?appId=123&fileId=9054


- 34 -

Term Description

"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": "ERROR",




]

}


- 35 -

Get Concepts API to retrieve concepts for an application.

Term Description

Prerequisite


URL

/kdx/suggest/terms/concepts/

Method

GET

URL Parameters

Required appId=[string] (Application id of the app for which the concepts are being requested)


Header Parameters


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. 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

http://localhost:8082/execueWSWebApp/kdx/suggest/terms/concepts/111

http://localhost:8082/execueWSWebApp/kdx/suggest/terms/concepts/111


- 36 -

Term Description

"totalPages": Total number of pages

Success Response


{ "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 are 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 (assuming we know the total items by running the default query at first instance). Moreover, therefore, the items per page will be displayed as a total number of concepts (items).

Error Response


{

"status": "ERROR",




- 37 -

Term Description

"details": [


] }


- 38 -

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


URL /udx/sc/getContentMappingInfo

Method

GET

URL Parameters

Required appId=[string] (Application id of the app for which the Content are being requested)


Header Parameters


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 "title": file name

http://localhost:9999/execueWSWebApp/udx/sc/getContentMappingInfo?appId=234

http://localhost:9999/execueWSWebApp/udx/sc/getContentMappingInfo?appId=234


- 39 -

Term Description

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,


- 40 -

Term Description

"contentId": 2737, "sourceItemId": "3413", "title": "Portal Solutions LLC_SOW_2016.07.25.pdf" }, { "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 } }


- 41 -

Term Description

Example 1 For example, If total items are 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). Moreover, therefore, the items per page will be displayed as a total number of files.

Error Response


{

"status": "ERROR",




]

}


- 42 -

Structured Search This 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 to the section Structured – Get App Data to retrieve actual data.

Term Description

Prerequisite


URL /app/find Method POST URL Parameters

NONE

Header Parameters


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

http://localhost:9876/execueWSWebApp/app/find


- 43 -

“searchString”: This key is mandatory. The API finds and returns the results for this search string with in the provided appId value. E.g., “searchString": ”Average bill rate by business unit and supplier.”

JSON response object: “result”: This list of the object contains the information about the data that is returned for the request. “appId”: The application id “data present”: [true/false] Whether the data present or not. Useful whether to go for the subsequent request to 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 the 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": "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" } ] }


- 44 -

Error Response


{

"status": "ERROR",




]

}


- 45 -

Get App Data This API helps in retrieving the data table for a given queryId.

Term Description

Prerequisite


URL /app/data Method POST URL Parameters

NONE

Header Parameters


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 the previous search result. For ex: “appId”: 113

JSON response object: “result”: This object contains the information about the data that is returned for the request. “data”: Data concerning the columns from meta object

“meta”: Explains the columns of the grid Success Response


{ "status": "OK", "message": "Success",

http://localhost:9876/execueWSWebApp/app/find


- 46 -

Term Description

"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



- 47 -

Term Description

{

"status": "ERROR",




]

}


- 48 -

Query Parameters Parameters are options you can pass with the endpoint (such as specifying the response format or the amount returned) to influence the response. There are four types of parameters: header parameters, path parameters, query string parameters, and request body parameters.

The different types of parameters are often documented in separate groups on the same page. Not all endpoints contain each type of parameter.

The REST APIs have four types of parameters:

Header parameters: Parameters included in the request header, usually related to authorization.

Path parameters: Parameters within the path of the endpoint, before the query string (?). These are usually set off within curly braces.

Query string parameters: Parameters in the query string of the endpoint, after the?

Request body parameters: Parameters included in the request body. Usually submitted as JSON.


- 49 -

Status Codes All 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 codes Response code Description 200 — Success Everything went smooth. 401 — Unauthorized Missing or incorrect API token in the 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 a 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.


- 50 -

Utility Software Standalone 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.

The suggested client can be found at https://github.com/wiztools/rest-client

Browser Plugin based REST Client

Semantify suggests using Advanced REST Client from Chrome Store or any other plugin as per the comfort of Client for API testing purposes. The suggested plugin can be found at https://advancedrestclient.com/

https://github.com/wiztools/rest-client

https://advancedrestclient.com/

Documents

API Guide · 2 days ago · Semantify Proprietary & Confidential - 2 Table of Contents OVERVIEW ..... - 4 - CONVENTIONS..... - 4 - CURRENT VERSION..... - 4 -