Map execution API

The trading engine map execution API supports a Representational State Transfer (REST) model for listing, detailing and running map components that are deployed on B2Bi servers.

The principal use case for this API is to run maps in the Axway API Gateway product.

This chapter includes information about the API resources for:

  • Listing the maps that are available on a B2Bi server
  • Getting details of the individual maps deployed on a B2Bi server
  • Running a map on a server

A Swagger UI with a graphic representation of the API is available on the B2Bi Server.

Prerequisite

To enable this functionality, during installation of the B2Bi Server you must select the option "Execute map as a service". You also must assign a port for this functionality during the installation process.

After installation you can reconfigure the Map Service port in System Profile Manager.

Authorization

The API requires the use Basic HTTP authorization (www-authenticate: Basic) on all operations.

To use this API you must have a B2Bi user account with user name and password. This user has to have either the ‘admin’ role or another role for which the permissions ‘Access APIs' and ‘Map as a service’ have been enabled.

Limitations

  • The map execution API is not available when B2Bi is configured to use Passport authentication.
  • The service only supports Data Mapper maps, DML maps, MBC and JMC components.
  • It’s not possible to execute a map component that contains a connection (JDBC, OracleSP, SAP or WebServices connection).
  • It is not possible to execute map components that have multiple outputs.
  • It is not possible to execute a map component that has no output defined.

Uniform Resource Identifiers (URIs)

/v1/mapservice/maps

The following operation is supported on this resource:

GET

List all available map components created on the B2Bi server.

Use the Swagger representation to see the details of the operation.

 

/v1/mapservice/maps{id}

The following operation is supported on this resource:

GET

Get detailed information about a map components with the given identifier, {id}.

Use the Swagger representation to see the details of the operation.

 

/v1/mapservice/runmap

The following operation is supported on this resource:

POST

Execute a map component.

Use the Swagger representation to see the details of the operation.

Swagger representation of the API

To explore and test the API, a Swagger UI and representation of the API is available on the B2Bi server.

The example screen shots in this topic are based on a setup in which a map component has been created that is named ‘Remove CR’.

This example map component takes the input and removes any found CR characters (\r), and returns the result. This MBC is a standard deployed resource.

The following screen shot shows a view of the resource in the "add a component" wizard of the B2Bi user interface. This is the component we handle in the Swagger API examples below:

Access the Swagger interface

  1. Open a browser and enter the URL: http://<host>:<port>/v1/mapservice/apidocs
  2. Where:
    1. <host> is the machine where you installed the B2Bi server
    2. <port> is the Map Service Execution port you assigned using the installer or System Profile Manager
  3. The browser prompts you to enter your B2Bi user and password credentials.
  4. When you open the interface you first view the B2Bi Map as a service API welcome screen:
  5. Click maps or List Operations.
  6. The interface lists the three available operartions for managing maps as a service:

Operations

GET/maps

Use GET/maps to obtain a list of all the map components that are available on the system.

To get a list of available maps via Swagger:

  1. Click GET/maps in the Swagger main page.
  2. Click Try it out!

Response: Lists of all of the maps available on the server, and for each map the following information:

  • id – The map ID
  • name – The B2Bi friendly name
  • type – The map type (MBC (Message Builder Component) or MD (Map Designer) or DM (DataMapper))

Example response showing the "Remove CR" component:

GET/maps{id}

Use GET/maps{id} to obtain details about a specific map specified by {id}. In order to run a map you need to know the input and output parameters for the map. This resource returns this information.

To get details of a specific map via Swagger:

  1. Click GET/maps{id} in the Swagger main page.
  2. Enter a map ID in the id field.
  3. Click Try it out!

Example response showing the "Remove CR" component details:

Response: For the map with the given ID, this API returns the following information:

  • id – The map ID
  • name – The B2Bi friendly name
  • type – The map type (MBC (Message Builder Component) or MD (Map Designer) or DM (DataMaper))
  • inputFormat – Format of the input document ( EDIFACT/IDOC/INHOUSE/NACHA/TRADACOMS/VDA/X12/XML/XSD)
  • outputFormat – Format of the output document ( EDIFACT/IDOC/INHOUSE/NACHA/TRADACOMS/VDA/X12/XML/XSD)
  • parameters – List of all parameters (id/name/type)

POST/runmap

Use POST/runmap to run a map that available on the B2Bi server.

To run a map in Swagger:

  1. Click POST/runmap in the Swagger main page.
  2. Click on the model schema to transfer the schema to the POST message body frame.
  3. Edit the message body, adding the ID of the map to run, and complete any required parameters.
  4. Example message body for the "Remove CR" component:
  5. Reminder: To get a full list of parameters for any component, you can run GET/maps{id}.
  6. Click Try it out!

Example response showing the "Remove CR" parameters:

POST/runmap: Handling binary data

B2Bi uses Base64 encoding to handle the binary data in the JSON data sent to and from the server.

If the map input data sent to the server is binary data, the input must be Base64 encoded before it is added to the “data” string. This means that you must set the boolean parameter "base64Encoded" to "true".

If the map returns binary data, you must set the map configuration parameter "Output_Base64Encode" to "true". The server then Base64 encodes the output data returned from the map.

Example:

  1. Edit the message body:
  2. Click Try it out!.
  3. Response:

Related Links