8.5

Edit

VDS Gateway Service REST API

note

The gateway service is usually bound to the /gateway-service/ context.

Search HyperModels

List HyperModels

GET {GatewayURL}:8080/listHyperModels

Example response:

[
    {
        "id": 12,
        "hyperModelName": "dividends",
        "created": "2015-08-27",
        "versions": []
    },
    {
        "id": 13,
        "hyperModelName": "dividends-relatedness-classification",
        "created": "2015-08-27",
        "versions": []
    },
    {
        "id": 14,
        "hyperModelName": "information_extraction",
        "created": "2015-08-27",
        "versions": []
    },
    {
        "id": 15,
        "hyperModelName": "labeltest",
        "created": "2015-08-27",
        "versions": []
    },
    {
        "id": 16,
        "hyperModelName": "ml-models-my-model-9",
        "created": "2015-08-27",
        "versions": []
    },
    {
        "id": 17,
        "hyperModelName": "online_ie",
        "created": "2015-08-27",
        "versions": []
    },
    {
        "id": 18,
        "hyperModelName": "ssi",
        "created": "2015-08-27",
        "versions": []
    }
]

Check Eval availability on HyperModel

GET {GatewayURL}:8080/isEvalAvailable?name={ModelName}&docsNum={NumberOfDocs}&delta={Delta}

Example response:

{"available":true,"hyperModelVersion":"1.0"}

Or:

{"available":false,"hyperModelVersion":null}

Get HyperModel details

GET {GatewayURL}:8080/hyperModelDetails?name={ModelName}&version={ModelVersion}

Example response:

{
    "mainHyperModel": {
        "code": "online_ie",
        "fqn": "com.workfusion.nlp.uima.workflow.model.ie.online.OnlineIeHyperModel",
        "title": "Online information extraction",
        "version": "1.0",
        "description": "Online information extraction description",
        "minDocs": 100,
        "minDelta": 10
    },
    "onlineModel": []
}

Deal with HyperModel

Start evaluation

POST {GatewayURL}:8080/startEval

Request

Request body should contain the following JSON (example):

{
    "modelName" : "ml-models-my-model-9",
    "modelVersion" : "1.0",
    "experimentGroupId" : "test1",
    "parameters" : {
        "answers" : "{Encoded JSON}",
        "contextInfo" : "egid:11ee99fff,src:my-instance",
        "cluster" : "mesos"
  }
}

The contextInfo parmeter can be added to the parameters list. It will be logged to service logs (gateway-service, ducc-adapater, and so on).

  1. A cluster parameter has be added to override target cluster for a train process. Possible values: mesos or ducc.
  2. Added perameters for HPO configuration:
    • hpoIterationLimit: limit for amount of iterations made by HPO
    • hpoMaxNumOfExp: max number of experiments to execute by HPO
    • hpoTimeLimit: time limit for HPO execution

Sample response

{
  "evalJobId" : "9364",
  "version" : "1.2.3",
  "correlationId" : "startEval/gjlsXdEPRmWal7aH1m271g"
}

Check evaluation status

GET {GatewayURL}:8080/evalStatus?egid={ExperimentJobId}[&cluster=mesos|ducc]

Sample COMPLETED response:

{
  "evalStatus": "COMPLETED",
  "errorMessage": null,
  "results": {
    "1234567890": [
      {
        "tag": "No",
        "precision": 0.9291375497567447,
        "recall": 0.9882352941176471,
        "f1": 0.9577756592235942
      },
      {
        "tag": "Yes",
        "precision": 0.5,
        "recall": 0.4,
        "f1": 0.4444444444444445
      }
    ]
  }
}

Sample COMPLETED response with error message (possibly for online hyper-model):

{
    "evalStatus": "COMPLETED",
    "errorMessage": "Unable to get meta-evaluation results for COMPLETED eval job, 
        ExperimentGroupID: test1, 
        status: {\"code\":\"0\",\"stateSequence\":[],\"rationale\":\"\",\"total\":\"0\",\"done\":\"0\",\"error\":\"0\",\"retry\":\"0\",\"procs\":\"0\",\"remotePids\":[],\"errorLogs\":[],\"nodes\":[]}\n. 
        This is due to DUCC malfunction or eval was running for Online Hyper-Model",
    "results": null
}

The list of Eval job statuses is as follows:

StatusDescription
IN_PROGRESSEval job is in progress
COMPLETEDEval job is successfully completed. The error may contain either results or errorMessage (in case results are not available)
TERMINATEDEval job was terminated manually via Gateway REST API or DUCC web-console
FAILEDEval job is failed. The response should contain the error message.

Stop Eval job

POST {GatewayURL}:8080/stopEval[?cluster=mesos|ducc]

The following JSON should be supplied with request body:

{
    "experimentGroupId" : "{EGID}"
}

The expected response is always without the body:

HTTP 200

Extract v1

POST {GatewayURL}:8080/extract

Request

The following JSON should be supplied with the request body:

{
  "modelId" : "{ModelCode}",
  "modelVersion" : "{ModelVesrion}",
  "experimentGroup" : "{EGID}",
  "experimentId" : "{ExperimentId}",
  "contextInfo": "document:doc_FE9323,src:my-instance"
  "document" : "{Document}",
  "parameters" : {
     "param1" : "valStr",
     "param2" : valNum,
    ...
  }
}

parameters refers to optional additional parameters. Can be omitted. The supported parameters are as follows:

  • modelResponseTimeout: model response timeout (seconds)
  • maxSubmodelsPerExtract (only for hypermodel with multi-submodels): maximum number of sub-models per extract. If the actual number of submodels exceeds maxSubmodelsPerExtract, the request will be split to sub-models subsets and re-issued for each subset. After each subset responses received, they are aggregated to overall results.
  • submodel: do not set this parameter manually, as it used by request-per-model-subset mechanism (see the parameter description above).

Document is usually JSON:

{
  "textParts" : ["{Document Content}"]
}

{
  ...
  "document" : "{"textParts" : ["{Document Content}"]}",
  ...
}

Response

Sample Extract response:

{Response body}

Essentially, the response to Gateway clients will be the same as a response from Hyper-Model.

Extract v2

POST {GatewayURL}:8080/extract-v2

The same as Extract v1 but return structured response with correlationId:

{
  "result": "{\"score\":0.5253121682166522,\"category\":\"Bank_of_America\"}",
  "correlationId": "extract-v2/HZMQtTa1Ry2QdWTcqvbrYg"
}

HTTP response codes

CodeDescription
200OK. Normal response, the body will contain {Response body} from above.
500Internal server error. Causes due to failure on gateway service, queue broker or hyper-model side. The response body will contain a string with error details. Such responses should be handled on WF side.
504Gateway Timed Out. This can be caused by queue broker or failed Hyper-Model when Hyper-Model is unable to send response to Gateway Service. Such responses should be handled on the WorkFusion side.

All other codes are kind of "Runtime Exception" and should be handled differently in a BP.

← Application Programming Interfaces (APIs)Next →