REST Output Text Request

Text Rest Fields Configuration

This page describes the part of creating a REST Output when the request type is set to Text.

  1. Enter an endpoint.

    • Shown on the the REST Connection form, the final request URL is the concatenation of the base URL from the REST Connection and endpoint. The base URL can (but isn't required to) have an ending slash character. Similarly, the endpoint can (but isn't required to) have a starting slash character. Hero Platform_ can handle it.

    • If the full URL of the endpoint is https://domain.com:12/api/v2/issues and if the base URL contains https://domain.com:12/api/  the endpoint field's value should be either /v2/issues or v2/issues. 

    • Some endpoints require the use of path parameters. This means the endpoint path has path segments that vary request by request.

      • For example, when updating ticket 123 from project PROJECT1, the request should be sent to https://domain.com:12/api/v2/project/PROJECT1/issue/123 for updating ticket 456 from the same project. The request should be sent to: https://domain.com:12/api/v2/project/PROJECT1/issue/456. 
        If the base URL contains https://domain.com:12/api/v2/ the endpoint value should be /project/${project}/issue/${issue}. Fields appear for project and issue in the field mapping table below. These parameters will be resolved before each HTTP request from the actual tuple. Of course, if project is always the same for the Output, it is possible use /project/PROJECT1/issue/${issue} and have only field mapping for issue.

  2. Enter additional request headers, query parameters, and/or cookie parameters with their values.

    • These parameters are merged with the Connection parameters. If a parameter is set on both forms, the Output's value overrides the value from the Connection.

    • The terms "Header", "Query" and "Cookie" parameters are HTTP terms that reflect the location of the parameter in the HTTP request. The API documentation states the exact location and the name of the required and the optional parameters. 

    • Header and cookie parameters are generally used for authentication/authorization or sending preferred language, location, response format, etc.

    • Query parameters are generally used together with HTTP GET requests. (E.g., page size, offset, search term, and id)

    • Example: Some API's can consume both XML and JSON request bodies. These expect to have the content-type header with the value application/json if your request body contains JSON.

    • By default, there are already two request headers added to a new Output. These request headers are usually useful (see above bullet point) or ignored by the server. Consult with the API documentation and remove or edit the headers accordingly.


  3. Select a REST method from the drop-down list.

    • The selected endpoint along with the REST API's documentation determine what HTTP method should be selected.

    • There are not any strict standards about how REST API's should be built, but generally the:

      • GET method is for getting a single entity or listing entities.

      • POST method is for the creation (or updating) entities or for triggering actions. (E.g., logout, start batch export, etc)

      • PATCH, PUT, DELETE  methods are also used for triggering entity modifications. (update, update, delete)

      • HEAD method is for checking resource availability.

    • Outputs use POST, PATCH, PUT and DELETE methods in most cases. Using GET or HEAD methods for an Output can indicate a Flow design issue or an edge case.


  4. Select parameter escaping.

    • Parameter escaping is how parameters are resolved in the body.

    • REST API endpoints expect the format of the body (e.g., JSON). These formats are very strict. (E.g., This is a valid JSON {"a": "text"} , but this is not: {"a": "text} because the text string is not closed with double quotes)

    • Resolved variables can possibly break the syntax depending on the content of a JSON if they are not escaped. (E.g., {"message": "${msg}"} is in the body. If the mapped field contains "Go ahead" then {"message":"Go ahead"}  is sent after the resolution. That is a valid JSON. If the mapped field contains "Carol said "Go ahead"" and the resolved JSON is: {"message":"Carol said "Go ahead""}. That is an invalid JSON.  The correct form is {"message":"Carol said \"Go ahead\""}. This is what the JSON escaper does. It escapes the parameter's value in the body.

    • In some other cases, the desired behavior is not to escape the parameter's value. If a valid JSON is already in the input field, it can be added in the body without further transformations. This is what No escape does.


  5. Fill the body text.

    It is often required to send a request body when the POST, PATH, and PUT methods are used. The required format of the body is described in the REST API endpoint's definition.


    Example

    The current API requires a JSON in the body as follows: 

    {
  "name": {
    "first": "Andy",
    "last": "Brown"
  },
  "age": 30,
  "carId": "123-123-123-123"
}

    In this example, "name" is an object with "first" and "last" string fields. "age" is a number and "carId" is a string (but can be null if the current person doesn't have a car.)

    The body in Hero Platform_ can be:

    {
  "name": {
    "first": "${first}",
    "last": "${last}"
  },
  "age": ${age},
  "carId": "${carId}"
}

    Before each HTTP request, the parameters are resolved from the actual tuple.


    Variable placing and null handling

    Placing the double quotes and resulting a valid JSON is each users responsibility. In the case when the parameter's value is null, Hero Platform_ has built in replacement logic.

    If the body is defined in the following format: {"a": ${field}} (no double quotes around the param)

    • the input field is a Long and null value: {"a": null }

    • the input field is a Long and 123: {"a": 123 }

    • the input field is a String and "123": {"a": 123 }

    If the variable is defined in the following format {"a": "${field}" }  (there are double quotes around the param)

    • the input field is a Long and null value: {"a": null } (without double quotes)

    • the input field is a String and null value: {"a": null } (without double quotes)

    • the input field is a Long and 123: {"a": "123" }

    • the input field is a String and "123": {"a": "123" }


  6. Tuple field names are generated by variables used in the endpoint, header, query parameters, cookie parameters, and body.

Search