Create a REST Input

To create an Input for REST, you must have a REST Connection.

Create an Input for REST in Hero Platform_

  1. Open Hero Platform_.
  2. Open Integration from the navigation menu and select Inputs.
  3. Click Create New Input.

  4. Enter a name for the REST Input and select a REST Connection from the drop-down list.
  5. Enter an endpoint.

    • As discussed 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 an starting slash character. Hero Platform_ can handle it.
    • If the full URL of the endpoint is https://doman.com:12/api/v2/issues and if the base URL contains https://doman.com:12/api/  the endpoint field's value should be either /v2/issues or v2/issue
  6. Enter additional request headers, query and/or cookie parameters with their values.

    • These parameters are merged with the Connection parameters. If a parameter is set on both forms, the Input'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 often used for authentication/authorization or sending preferred language, location, response format, etc.

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

    • Example: Some API's can produce both XML and JSON responses. If the request contains the Accept header with the value application/json the response will be in JSON format. If not, by default they are producing the format in XML format.

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

  7. 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.
    • Inputs use the GET method in the most cases. Using other methods for Inputs can indicate a Flow design issue or an edge case.

  8. Select a pagination strategy from the drop-down list.

    Paginations are very vendor specific solutions for listing numerous entities with multiple HTTP request.

    Example: For Jira,  No Pagination or Jira pagination can be selected (if the endpoint supports it), but not the others.

    • No Pagination
    • Jira
    • Github
    • Slack Cursor
    • Zendesk (Cursor)

  9. Enter the body text (Optional)

    • Except in edge cases, the body text should remain empty.

    • Body text is mostly used together with POST, PATCH, PUT requests. It is unlikely for an Input's method to be something other than GET. 

  10. Select the input parser and fill it's configuration: Work with Parsers

    • JSON (or possibly TEXT) parsers are usually used for JSON responses.

  11. Mark the box to show the detected field response (optional, only for feedback for you)
  12. Click the refresh icon to display the Input field mapping.

    • Confirm or change field names.
    • Confirm or change field data types.
    • Remove or confirm the arrangement of fields.

    Warning

    The field mapping detection executes a real API call with the sample data. This action can cause changes on the server side when using POST, PUT, PATCH, and DELETE methods.

  13. Click OK to save the Input configuration.