Create a REST Connection

Introduction

This page discusses using the REST connector for web applications, such Zendesk, Jira, Salesforce and many others.

These web applications have web user interface for users doing their everyday jobs. They access and modify entities such as: tickets, labels, organizations, projects, etc.

Many web applications also expose APIs (Application Programming Interface). APIs are used so that other applications can interact with them (I.e. it enables applications to access and modify entities similarly as people do.)

With the this Rest connector (as well as the REST Input, Lookup, and Output) Hero Platform_ can be used to interact with these web applications. 


Before Starting with the Hero Platform_ Rest Connector

You should have:

  • a general understanding about how HTTP and Rest APIs work.

  • the documentation of the AP that you need to integrate.

  • the address of the API that you need to integrate (a URL).

  • permission to access the API that you need to integrate. Typically obtaining an username-password pair or a character chain provided by the owner, the administrator, or user interface of the API.

This page helps to explain the above topics. At the end of this page you will find links for the next steps.

What is HTTP

Being familiar with HTTP protocol important because both the API documentation and Hero Platform_'s user interface are using this knowledge extensively.

Make sure, you are familiar with the meaning of: server, client, request, response, header, query, path parameter, HTTP methods and status codes. If not, spend an hour and read the first nine modules from: https://www.tutorialspoint.com/http/

Use HTTPS

HTTPS is an extension of HTTP using secure communication. That means while using HTTPS you are using the same HTTP methods, headers, status codes, etc but the network traffic is encrypted. You should always prefer HTTPS communication over HTTP unless you have a really good reason not to.

See: https://en.wikipedia.org/wiki/HTTPS#Difference_from_HTTP

Rest APIs

Based on the HTTP protocol, web applications can expose APIs. If you are new to this topic, read: https://idratherbewriting.com/learnapidoc/docapis_what_is_a_rest_api.html or the full introduction chapter from: https://idratherbewriting.com/learnapidoc/docapis_introtoapis.html

API documentation

With the general understanding of HTTP and Rest APIs, the next step to understand the answer to the question: “What you can do with a Rest API” and “How you can achieve it”. The answers to these questions are highly depend on the actual Rest API you are using. Different web applications have different functionality and different endpoints, parameter names, required headers, and so on.

Take a look at two these different Rest API documentations.

Scan through the documentations and notice:

  • they are offering different functionalities.

  • they are expecting different ways of authentication. (Giphy uses a query parameter, Words API uses HTTP headers for the same purpose.)

  • the expected request URL’s and parameters are different for each endpoint.

  • the responses are different for each endpoint.

  • both Rest API documentations discuss the format of an expected HTTP request and the format of the HTTP response for the endpoints.

In conclusion: To use Hero Platform_ for interacting with another web application, you should have the comprehensive documentation about that specific Rest API.

Summary

Using a Rest API means sending HTTP requests to a server and using the HTTP responses.

The server expects:

  • HTTP request fields to authenticate the client.
  • fields to identify what endpoint to use.
  • fields to give parameters to the endpoint.

On each request, the server executes logic internally and sends a response to the client with the following information:

  • If the request was successful or unsuccessful. (E.g. The request was incomprehensible, unauthorized ,or another error occurred.)

  • The server can send data back to the users. This is not a requirement. A successful REST call may generate no server response to the user.

It’s the client’s responsibility to send the right HTTP request in the right format to the right server. Rest APIs usually have human readable documentation to make the process as clear as possible.

Hero Platform_'s REST connector is an HTTP client. It is flexible enough to work with different Rest API’s but must be configured according to the API's documentation.

Next Steps



Search