Cataloged Map Invocation

Edit online

Cataloging a map simplifies calls to the map and generates Swagger documentation that describes the APIs. The catalog provides a way to expose maps as services and to hide the implementation details of the services.

A map is defined in the catalog as a JSON document, like the 1in1out map example that is defined as following:

{
    "name": "1in1out",
    "summary": "Single input & single output",
    "description": "Uppercases the output from a single input",
    "tags": [ "Test" ],
    "inputs": [
      {
        "card_number": 1,
        "mime_type": "text/plain", 
        "description": "Plain text"        
      }
    ],
    "outputs": [
      {
        "card_number": 1,
        "mime_type": "text/plain",
        "description": "Uppercased input"
      }
    ],
    "url_path": "test/1in1out",
    "map_path": "OneInOneOut"
  }

The Swagger documentation for the Runtime Server defines the structure of the JSON document and explains the purpose of each element. You register a map in the catalog by posting the JSON document that defines it to the catalog directory. The following commands assume Runtime Server running on localhost (port 8080):

curl -X POST "http://localhost:8080/tx-rest/v1/itx/catalog" -H "Content-Type: application/json" -d @1in1out.json

Use Swagger to display map details and to test-run maps. To see the Swagger documentation for the cataloged maps, enter the following URL in a browser:

http://localhost:8080/tx-rest/api-docs?url=/tx-rest/v1/docs

By default, all the deployed map and flow endpoints for V2 REST API are shown in the Swagger web UI page, since the rest.defaultSwagger property defaults to v2. To see the cataloged map endpoints for V1 REST API, replace the text v2/docs in the search box with v1/itx/docs and select the Explore button in the Swagger web UI page.

You can run a cataloged map without specifying which cards to override or the name and path of the calling map. For example, the following command synchronously runs the cataloged version of the OneInOneOut map.

curl -X PUT -d "This is a test" "http://localhost:8080/tx-rest/v1/itx/maps/catalog/test/1in1out"

It should return the value:

THIS IS A TEST