IBM Integration Bus, Version 10.0.0.1 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS


Implementing an operation in a REST API

Use the REST API Description to implement operations in a REST API.

Before you begin

You must create a REST API in the IBM® Integration Toolkit, see Creating a REST API.

About this task

Operations in a REST API are implemented as a subflow. You must use the REST API Description to create an empty subflow for each operation. You can then implement the operation by adding any of the standard message flow nodes that are available with IBM Integration Bus to the subflow.

If you do not implement an operation, you can still deploy the REST API to an integration server. However, when an HTTP client attempts to call an unimplemented operation, an HTTP 501 Not Implemented status code is returned to the client.

Procedure

To implement an operation in a REST API, complete the following steps:

  1. Open the REST API Description for the REST API that contains the operation that you want to implement. The REST API Description is in the Application Development view under the REST API project.
  2. Locate the operation in the REST API Description. Operations are listed under the Operations heading, and are grouped by resource.
  3. Click the Implement the operation link. A new subflow is automatically created and opened.
    Note: After the operation has been implemented, the link changes to Open the operation, and if you click the link, the subflow reopens.
  4. Implement the operation by adding any of the standard message flow nodes that are available with IBM Integration Bus to the subflow.
  5. Information about the current operation is automatically placed into the local environment tree. You can use this information in your implementation if you want to determine which operation in the REST API was called, which HTTP method was used, the request path, or the request URI. For example, if you are sharing transformation logic across multiple operations, you can use this information to determine in which operation the REST API was called.
    Accessing current operation information in ESQL

    Check to see if the current operation was called by using an HTTP GET.

    IF InputLocalEnvironment.REST.Input.Method = 'GET' THEN
      -- Executed only if the current operation was called using an HTTP GET.
    END IF;

    Check to see if the current operation is the getAllCustomers operation.

    IF InputLocalEnvironment.REST.Input.Operation = 'getAllCustomers' THEN
      -- Executed only if the current operation is the getAllCustomers operation. 
    END IF;

    Create a log message with the request path.

    DECLARE logMessagePath CHARACTER 'Received request on path ' || InputLocalEnvironment.REST.Input.Path;

    Create a log message with the request URI.

    DECLARE logMessageURI CHARACTER 'Received request on URI  ' || InputLocalEnvironment.REST.Input.URI;
    Accessing current operation information in Java™

    Check to see if the current operation was called by using an HTTP GET.

    MbMessage inLocalEnvironment = inAssembly.getLocalEnvironment();
    MbElement leRestInput = inLocalEnvironment.getRootElement().getFirstElementByPath("/REST/Input");
    
    if (leRestInput.getFirstElementByPath("Method").getValueAsString().equals("GET")) {
      // Executed only if the current operation was called using an HTTP GET.
    }

    Check to see if the current operation is the getAllCustomers operation.

    if (leRestInput.getFirstElementByPath("Operation").getValueAsString().equals("getAllCustomers")) {
      // Executed only if the current operation is the getAllCustomers operation. 
    }

    Create a log message with the request path.

    String logMessagePath = "Received request on path " + leRestInput.getFirstElementByPath("Path").getValueAsString();

    Create a log message with the request URI.

    String logMessageURI = "Received request on URI  " + leRestInput.getFirstElementByPath("URI").getValueAsString();
    Accessing current operation information in .NET (C#)

    Check to see if the current operation was called by using an HTTP GET.

    NBMessage inLocalEnvironment = inputAssembly.LocalEnvironment;
    NBElement leRestInput = inLocalEnvironment.RootElement["REST"]["Input"];
    
    if (((String) leRestInput["Method"]) == "GET"){
      // Executed only if the current operation was called using an HTTP GET.
    }

    Check to see if the current operation is the getAllCustomers operation.

    if (((String) leRestInput["Operation"]) == "getAllCustomers") {
      //Executed only if the current operation is the getAllCustomers operation. 
    }

    Create a log message with the request path.

    String logMessagePath = "Received request on path " + ((String) leRestInput["Path"]);

    Create a log message with the request URI.

    String logMessageURI = "Received request on URI  " + ((String)leRestInput["URI"]);
    Accessing current operation information in a message map
    You can access the current operation information in a message map. The current operation information is available as a set of elements, which are named Method, Operation, Path, and URI, in a Message Assembly that includes the Local Environment, under Local Environment > REST > Input folder. For more information, see Mapping data in the local environment tree.
  6. If the definition of an operation includes one or more parameters, the names and values of those parameters are automatically placed into the local environment tree, but only if those parameters are provided by the HTTP client that is calling the operation. Optional or missing parameters are not placed into the local environment tree. Parameters are always placed into the local environment tree as character (string) elements, where the name of each element is the name of the parameter and the value of the element is the value of the parameter.
    Accessing parameter values in ESQL

    Check to see if the parameter named 'max' is supplied.

    DECLARE max INTEGER -1;
    IF FIELDTYPE(InputLocalEnvironment.REST.Input.Parameters.max) IS NOT NULL THEN
      SET max = InputLocalEnvironment.REST.Input.Parameters.max;
    END IF;
    Accessing parameter values in Java

    Check to see if the parameter named 'max' is supplied.

    MbElement maxElement = inLocalEnvironment.getRootElement().getFirstElementByPath("/REST/Input/Parameters/max");
    int max = -1;
    if (maxElement != null) {
      max = Integer.valueOf(maxElement.getValueAsString());
    }
    Accessing parameter values in .NET (C#)

    Check to see if the parameter named 'max' is supplied.

    NBElement maxElement = inLocalEnvironment.RootElement["REST"]["Input"]["Parameters"]["max"];
    int max = -1;
    if (max != null){
      max = (int) maxElement;
    }
    Accessing parameter values in a message map
    You can access parameter values in a message map. All parameters are available as set of elements, where the elements have the same name as the parameter name, in a Message Assembly that includes the Local Environment, under Local Environment > REST > Input > Parameters folder. Because the message maps do not have access to the parameter names, the Parameters folder includes a single element to which you must add user-defined elements, see Mapping data in the local environment tree and Defining user-defined elements.
  7. Depending on the HTTP method of the operation, the operation can accept data from the HTTP client in the request body. REST APIs in IBM Integration Bus are configured by default to process JSON data. For more information about processing JSON data that was passed in the request body, and creating JSON data to send as the response body, see JSON parser and domain. You can also use a message map to process JSON data. For more information, see Creating or transforming a JSON output message by using a message map.

Results

The operation is implemented in the REST API.

What to do next

You must package and deploy your REST API to an integration server, see Packaging and deploying a REST API.
You can also complete the following optional tasks:

bi12020_.htm | Last updated 2015-05-28 20:52:44