Working with HTTP REST

To design a Semarchy xDI HTTP REST workflow, you first need to design and configure HTTP REST metadata. Afterwards, add it to a mapping, and map the datastores to its fields.

Metadata structure

HTTP REST metadata is a tree structure with nested nodes. Each node has its own parameters to control aspects of the integration flow. The overall structure is as follows:

  • The metadata object holds a top-level metadata node with base parameters.

  • The top-level node holds one or more path nodes, which can also nest themselves. They represent an HTTP endpoint.

  • Path nodes hold operation nodes, which correspond to an HTTP method.

  • Operation nodes hold request parameters, request bodies, and responses.

  • Request Body nodes hold HTTP messages, as single or multipart messages. These may also hold structured data such as JSON.

  • Responses nodes contain nodes for HTTP responses, which themselves hold headers and HTTP messages.

Request parameters, response headers, and messages need their input and output assigned in a mapping.

Some nodes have URL or path parameters, which come together to create the HTTP endpoint. These parameters should not contain encoded URLs, as xDI encodes URLs itself.

Mappings

To design an integration flow around REST APIs, drag an operation node to an xDI mapping. This operation always calls the same endpoint, which is constructed from the metadata’s path nodes that contain the operation.

For example, take the following nested metadata structure:

Top-level node (URL: http://hostname:8080/)
└── Path node 1 (Path: endpoint)
    └── Path node 2 (Path: base)
        └── Operation node GET

Dragging and dropping this GET operation to a mapping creates an object that sends a GET request to http://hostname:8080/endpoint/base.

Input and output

When you add an operation from HTTP REST metadata to a mapping, you can map its nested parameters and messages like any other mapping object.

  • Request parameters, and Request Body messages, take inputs from other sources. Map data from a datastore such as file or database fields.

  • Responses and their parameters create output data that you can map to a datastore.

Integration templates

In a mapping, you can also open the HTTP REST metadata integration template to control more parameters, such as error handling.