Cataloging a map

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, similar to the 1in1out map example that's included in the tutorial:

{
    "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 ITX REST API 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 specified on rest.persistence.catalog in the install_dir/config.yaml file. For example:

> curl -X POST "http://localhost:8080/tx-rest/v1/itx/catalog" -H "Content-Type: application/json" -d @..\descriptors\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/itx/docs

If the tx-rest.war file is installed on a server other than the local host, adjust the host name.

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. Compare it to the direct call that runs the same map in Synchronous direct calls:

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