This REST Handler contains:

  • Endpoints that return Saga configuration and build information
  • Endpoints to process text and return the interpretation graph





POST saga/_saga/processText


  • Will return a Saga interpretation graph in the format specified
  • By default, it returns the graph in HTML format which is used by the UI
  • It also can return JSON or plain text

Parameters

  • q ( type=string | required ) - This is the text to process
  • tags ( type=string array | required ) - List of tags to use to process the text
  • tag ( type=string | optional ) - Tag to use to process the text
  • processor ( type=string | optional ) - Pipeline or pipeline stage to use to process the text
  • splitRegex ( type=string | default=[\r\n ]+ | optional ) - Specifies the regex to use to split text into TEXT_BLOCKs
  • combine ( type=boolean | default=false | optional ) - If true, it will combine all the SEMANTIC_TAGs, which has same matching text and same confidence value
    • The combination includes the metadata, of every SEMANTIC_TAG
  • addComponents ( type=boolean | default=true | optional ) - If true, it will also add the components from the highest route confidence tokens.
  • compFields ( type=string array | optional ) - Applicable when addComponents is true. Indicates which components to add to the response
    • If missing all the components will be added
  • metadata ( type=boolean | default=false | optional ) - If true, it will add the metadata of the entities found in every SEMANTIC_TAG
  • type ( type=string | default=ux | optional ) - Specifies the format of the results. It could be one of these values: "ux", "text" or "json"
    • ux - Returns an output useful for Saga to show the graph on a web display.
    • text - Returns a "line" with the highest confidence route and a text representation of the graph.
    • json - Returns all the semantic tags on the graph.
  • pretty ( type=boolean | default=false | optional ) - Used to pretty format the JSON result

The parameters tags, tag and processor are mutually exclusive, only one is required, and the priority order is:

  1. tags
  2. tag
  3. processor


Request Examples

curl -X POST \
  http://localhost:8080/saga/_saga/processText \
  -H 'Content-Type: application/json' \
  -d '
{
    "q": "I like traveling with Air Paris",
    "tags": ["airline"],
    "combine": true,
    "addComponents": true,
    "compFields": "paris",
    "splitRegex": "[\r\n]+",
    "type": "text",
    "pretty": true
}'

Response

{
  "_success": true,
  "data": {
    "line": [
      {
        "stage": "WhitespaceTokenizer",
        "confidence": 0.5,
        "match": "I",
        "flags": [
          "ORIGINAL",
          "ALL_UPPER_CASE",
          "TOKEN"
        ],
        "text": "I",
        "startPos": 0,
        "endPos": 1
      },
      {
        "stage": "WhitespaceTokenizer",
        "confidence": 0.5,
        "match": "like",
        "flags": [
          "ORIGINAL",
          "TOKEN",
          "ALL_LOWER_CASE"
        ],
        "text": "like",
        "startPos": 2,
        "endPos": 6
      },
      {
        "stage": "WhitespaceTokenizer",
        "confidence": 0.5,
        "match": "traveling",
        "flags": [
          "ORIGINAL",
          "TOKEN",
          "ALL_LOWER_CASE"
        ],
        "text": "traveling",
        "startPos": 7,
        "endPos": 16
      },
      {
        "stage": "WhitespaceTokenizer",
        "confidence": 0.4,
        "match": "with",
        "flags": [
          "ORIGINAL",
          "STOP_WORD",
          "TOKEN",
          "ALL_LOWER_CASE"
        ],
        "text": "with",
        "startPos": 17,
        "endPos": 21
      },
      {
        "components": [
          {
            "stage": "CaseAnalysis",
            "confidence": 0.45,
            "match": "Paris",
            "flags": [
              "ORIGINAL",
              "LOWERED",
              "TOKEN",
              "ALL_LOWER_CASE"
            ],
            "text": "paris",
            "startPos": 26,
            "endPos": 31
          }
        ],
        "stage": "DictionaryTagger",
        "confidence": 0.6975,
        "display": "Air Paris",
        "match": "Air Paris",
        "flags": [
          "SEMANTIC_TAG",
          "ENTITY"
        ],
        "text": "{airline}",
        "id": "34365531",
        "startPos": 22,
        "endPos": 31,
        "tags": [
          "airline"
        ]
      }
    ],
    "graph": " V-----------[I like traveling with Air Paris]-----------V \n ^-[I]-V-[like]-V-[traveling]-V-[with]-V-[Air]-V-[Paris]-^ \n ^-[i]-^                               ^-[air]-^-[paris]-^ \n                                       ^---[{airline}]---^ \n"
  }
}



POST saga/_saga/processBatch


  • Will return a Saga interpretation graph in the format specified
  • By default, it returns the graph in HTML format which is used by the UI
  • It also can return JSON or plain text

Parameters

  • batch ( type=string array | required ) - List of texts to process
  • tags ( type=string array | required ) - List of tags to use to process the text
  • tag ( type=string | optional ) - Tag to use to process the text
  • processor ( type=string | optional ) - Pipeline or pipeline stage to use to process the text
  • splitRegex ( type=string | default=[\r\n ]+ | optional ) - Specifies the regex to use to split text into TEXT_BLOCKs
  • combine ( type=boolean | default=false | optional ) - If true, it will combine all the SEMANTIC_TAGs, which has same matching text and same confidence value
    • The combination includes the metadata, of every SEMANTIC_TAG
  • addComponents ( type=boolean | default=true | optional ) - If true, it will also add the components from the highest route confidence tokens.
  • compFields ( type=string array | optional ) - Applicable when addComponents is true. Indicates which components to add to the response
    • If missing all the components will be added
  • metadata ( type=boolean | default=false | optional ) - If true, it will add the metadata of the entities found in every SEMANTIC_TAG

The parameters tags, tag and processor are mutually exclusive, only one is required, and the priority order is:

  1. tags
  2. tag
  3. processor


Request Examples

curl -X POST \
  http://localhost:8080/saga/_saga/processBatch \
  -H 'Content-Type: application/json' \
  -d '
{
    "batch": ["I like traveling with Air Paris", "I enjoy traveling with Delta"],
    "tags": ["airline"],
    "combine": true,
    "addComponents": true,
    "compFields": "paris"
}'

Response

[
    {
        "data": {
            "line": [
                {
                    "stage": "WhitespaceTokenizer",
                    "confidence": 0.5,
                    "match": "I",
                    "flags": [
                        "ORIGINAL",
                        "ALL_UPPER_CASE",
                        "TOKEN"
                    ],
                    "text": "I",
                    "startPos": 0,
                    "endPos": 1
                },
                {
                    "stage": "WhitespaceTokenizer",
                    "confidence": 0.5,
                    "match": "like",
                    "flags": [
                        "ORIGINAL",
                        "ALL_LOWER_CASE",
                        "TOKEN"
                    ],
                    "text": "like",
                    "startPos": 2,
                    "endPos": 6
                },
                {
                    "stage": "WhitespaceTokenizer",
                    "confidence": 0.5,
                    "match": "traveling",
                    "flags": [
                        "ORIGINAL",
                        "ALL_LOWER_CASE",
                        "TOKEN"
                    ],
                    "text": "traveling",
                    "startPos": 7,
                    "endPos": 16
                },
                {
                    "stage": "WhitespaceTokenizer",
                    "confidence": 0.4,
                    "match": "with",
                    "flags": [
                        "ORIGINAL",
                        "STOP_WORD",
                        "ALL_LOWER_CASE",
                        "TOKEN"
                    ],
                    "text": "with",
                    "startPos": 17,
                    "endPos": 21
                },
                {
                    "components": [
                        {
                            "stage": "CaseAnalysis",
                            "confidence": 0.45,
                            "match": "Paris",
                            "flags": [
                                "ORIGINAL",
                                "ALL_LOWER_CASE",
                                "LOWERED",
                                "TOKEN"
                            ],
                            "text": "paris",
                            "startPos": 26,
                            "endPos": 31
                        }
                    ],
                    "stage": "DictionaryTagger",
                    "confidence": 0.6975,
                    "display": "Air Paris",
                    "match": "Air Paris",
                    "flags": [
                        "ENTITY",
                        "SEMANTIC_TAG"
                    ],
                    "text": "{airline}",
                    "id": "34365531",
                    "startPos": 22,
                    "endPos": 31,
                    "tags": [
                        "airline"
                    ]
                }
            ],
            "matches": [
                {
                    "components": [
                        {
                            "stage": "CaseAnalysis",
                            "confidence": 0.45,
                            "match": "Paris",
                            "flags": [
                                "ORIGINAL",
                                "ALL_LOWER_CASE",
                                "LOWERED",
                                "TOKEN"
                            ],
                            "text": "paris",
                            "startPos": 26,
                            "endPos": 31
                        }
                    ],
                    "stage": "DictionaryTagger",
                    "confidence": 0.6975,
                    "display": "Air Paris",
                    "match": "Air Paris",
                    "flags": [
                        "ENTITY",
                        "SEMANTIC_TAG"
                    ],
                    "text": "{airline}",
                    "id": "34365531",
                    "startPos": 22,
                    "endPos": 31,
                    "tags": [
                        "airline"
                    ]
                }
            ]
        }
    },
    {
        "data": {
            "line": [
                {
                    "stage": "WhitespaceTokenizer",
                    "confidence": 0.5,
                    "match": "I",
                    "flags": [
                        "ORIGINAL",
                        "ALL_UPPER_CASE",
                        "TOKEN"
                    ],
                    "text": "I",
                    "startPos": 0,
                    "endPos": 1
                },
                {
                    "stage": "WhitespaceTokenizer",
                    "confidence": 0.5,
                    "match": "enjoy",
                    "flags": [
                        "ORIGINAL",
                        "ALL_LOWER_CASE",
                        "TOKEN"
                    ],
                    "text": "enjoy",
                    "startPos": 2,
                    "endPos": 7
                },
                {
                    "stage": "WhitespaceTokenizer",
                    "confidence": 0.5,
                    "match": "traveling",
                    "flags": [
                        "ORIGINAL",
                        "ALL_LOWER_CASE",
                        "TOKEN"
                    ],
                    "text": "traveling",
                    "startPos": 8,
                    "endPos": 17
                },
                {
                    "stage": "WhitespaceTokenizer",
                    "confidence": 0.4,
                    "match": "with",
                    "flags": [
                        "ORIGINAL",
                        "STOP_WORD",
                        "ALL_LOWER_CASE",
                        "TOKEN"
                    ],
                    "text": "with",
                    "startPos": 18,
                    "endPos": 22
                },
                {
                    "stage": "WhitespaceTokenizer",
                    "confidence": 0.5,
                    "match": "Delta",
                    "flags": [
                        "ORIGINAL",
                        "TOKEN",
                        "TITLE_CASE"
                    ],
                    "text": "Delta",
                    "startPos": 23,
                    "endPos": 28
                }
            ],
            "matches": [
                {
                    "stage": "DictionaryTagger",
                    "confidence": 0.44999999999999996,
                    "display": "Delta Air Lines",
                    "match": "Delta",
                    "flags": [
                        "ENTITY",
                        "SEMANTIC_TAG"
                    ],
                    "text": "{airline}",
                    "id": "188920",
                    "startPos": 23,
                    "endPos": 28,
                    "tags": [
                        "airline"
                    ]
                }
            ]
        }
    }
]



GET saga/_saga/solution


  • Returns the information of the solution currently being used.
  • A solution is basically the set of Elasticsearch indices in use

Request Examples

curl --location --request GET 'http://localhost:8080/saga/_saga/solution'

Notes

  • If you are not logged properly and try to use this request, it will return "Unauthorized" as response.
  • On Windows, change the single quotes for double quotes.

Response

"_success": true,
"elasticSearch": {
    "retries": 3,
    "delay": 5,
    "indexname": "saga",
    "nodeUrls": [
        "localhost:9200"
    ],
    "authentication": "none",
    "encryptionKey": "f123123##c#$#4GGVqFk7L9123123@*^",
    "timeout": 30
},
"display": "Saga"



GET saga/_saga/info


  • Returns build-specific and configuration information about Saga
  • Build information contains title, vendor, version, build revision and date
  • Configuration information contains the solution (Elastic index) and providers configured at the moment

Request Examples

curl --location --request GET 'http://localhost:8080/saga/_saga/info'

Notes

  • If you are not logged properly and try to use this request, it will return "Unauthorized" as response.
  • On Windows, change the single quotes for double quotes.

Response

"msg": "Saga API online",
"_success": true,
"buildInfo": {
    "Implementation-Title": "Saga Server",
    "Implementation-Build": "6b79d916e8ff9ad9efd742d4fbc8ce186f77c02d",
    "Implementation-Version": "1.3.1",
    "Implementation-Timestamp": "1609253821444",
    "Implementation-Vendor-Id": "com.accenture.saga",
    "Built-By": "jenkins",
    "Build-Jdk": "11.0.12",
    "Implementation-Branch": "develop"
},
"solutions": [
    {
        "elasticSearch": {
            "retries": 3,
            "delay": 5,
            "indexName": "saga",
            "nodeUrls": [
                "localhost:9200"
            ],
            "authentication": "none",
            "encryptionKey": "f123123##c#$#4GGVqFk7L9123123@*^",
            "timeout": 30
        },
        "display": "Saga"
    }
],
"exportSettings": {
    "maxSize": 40,
    "batchSize": 5000
},
"ssl": false,
"providers": [
    {
        "baseDir": "./config",
        "name": "filesystem-provider",
        "encryptionKey": "f123123##c#$#4GGVqFk7L9123123@*^",
        "type": "FileSystem"
    },
    {
        "indexName": "saga",
        "nodeUrls": [
            "localhost:9200"
        ],
        "name": "saga-provider",
        "exclude": [
            "updatedAt",
            "createdAt"
        ],
        "encryptionKey": "f123123##c#$#4GGVqFk7L9123123@*^",
        "type": "Elastic",
        "timestamp": "updatedAt",

        "authentication": "none"
    }
]



GET saga/_saga/stopServer


  • Stops the Saga Server

If you stop the server via HTTP request, it can only be restarted on-premise


Request Examples

curl --location --request GET 'http://localhost:8080/saga/_saga/stopServer'

Notes

  • If you are not logged properly and try to use this request, it will return "Unauthorized" as response.
  • On Windows, change the single quotes for double quotes.

Response

  • No labels