How to use the Custom REST Endpoint type

Introduction

The Custom REST Endpoint type empowers you with the ability to construct your very own endpoint, when you require a different type of endpoint that isn't currently available in the ONEiO framework. A comprehensive reference for all fields and their respective applications can be located in this article.

Should you require any guidance or support for your endpoint, feel free to reach out to us at support@oneio.cloud. We're here to assist you without hesitation!

Overview

In the following article, we'll take you step by step through a practical example of utilizing the Custom REST Endpoint to construct a personalized endpoint. 

1. General settings
2. Inbound settings
3. Outbound settings
4. Entity types and default message type settings

General settings

Let's delve into the integral components that constitute this endpoint:

• General: It contains all endpoint details such as the generic name, base URI, timezone, and more. This section also covers the authentication method you'll implement to access the specific app you wish to establish a connection with.
• Inbound: It includes the information required by ONEiO for seamless data reception. This allows the movement of data from your instance into the ONEiO system. The directional logic here is Your Instance→ ONEiO.
• Outbound: It includes all the essential information necessary for ONEiO to effectively transmit data to your instance. The directional logic here is ONEiO → Your Instance.

The General section is a requirement, whereas the remaining two sections are tailored according to your specific scenario. Consider this: if you're interested in developing a customized REST Endpoint for Zendesk (and just so you know, we happen to have our own Zendesk endpoint 😉), here is how you would need to set up the Custom REST endpoint to achieve the following goals: 

You might see that the Custom REST endpoint has lots of fields, but not all are required. This happens because each application has its own way of working and needs different information. But remember, you don't have to fill in all the fields, just the ones that your specific endpoint needs. You can find out which ones are necessary by checking the application's official documentation (like Zendesk's guides).

Inbound

When it comes to handling incoming data, your first task will involve deciding how the data will be collected. This decision is tailored to your endpoint, but within ONEiO, there are two methods encompassing three options available:

1. PUSH: This is the most common and widely supported method, utilized by a majority of applications. Your instance sends a request to ONEiO whenever a new update is available. 
   
   
2. PULL: The pull architecture works differently - here, ONEiO initiates the process by sending a request, and the server responds accordingly whether it has data or not. In this scenario, in ONEiO you define a polling interval (i.e. 10s, 30s, 1 min, etc.) which defines the frequency ONEiO sends requests to the server to check for updates.
   
   
3. PUSH & PULL: Many applications that possess a RESTful API offer support for both push and pull mechanisms. The choice between pull and push depends heavily on the specific use case at hand. The decision to use either pull or push revolves around the particular requirements of your scenario. In ONEiO, you can use both mechanics for the same endpoint in case you want to fetch different objects with different methods. For example, you might opt for PUSH to fetch tickets whenever a new ticket is generated or an update becomes available so that the change is reflected almost instantaneously. Conversely, you may prefer to use the PULL method to retrieve other data entities such as new contacts or companies that are less relevant less frequently (i.e. once daily).

Here are some setup examples using Zendesk:

Imagine we're aiming to fetch details about a Zendesk ticket. To achieve this, follow these steps within the General tab to input the basic endpoint information:

Here is how it will look like in ONEiO:

Now, let's configure the inbound flow to enable ONEiO to receive Zendesk tickets.

One of the initial choices involves selecting the method through which we'll bring data into ONEiO. This decision outlines whether ONEiO will gather messages from your system, regularly check your system for updates, or perhaps a blend of both. Occasionally, this decision might be predefined by the application rather than left to our discretion. As an illustration, for Autotask, the mechanism is set to PULL, since data retrieval requires active requesting and pulling into ONEiO.

In the case of Zendesk, you generally have the flexibility to employ either the PUSH or PULL mechanism. So, when it comes to Zendesk, the decision of how you opt to fetch the data is up to your preference.

Now, let's move on to exploring the implementation of the outbound flow, which involves sending information from ONEiO to Zendesk.

Outbound

Here the information you need to have is to know what is the content type of the data object you want to get, the method and the target for creating new tickets, and the method and the target for updating tickets.

For the outbound section, you need to know what is the API request to create a ticket and update a ticket for the application you are trying to connect. This information is found in the official docs of a specific application.

For example, for Zendesk the request for creating a ticket is:

POST /api/v2/tickets

and the request for updating a ticket is:

PUT /api/v2/tickets/{ticket_id}

Entity types and default message type settings

Now that we are all set with the general setup, let's go to the entity types section.

Here we need to define the data object.

Following our example, we know that in Zendesk the data object we want to use is the ticket, so let's click on +Add new entity type and name it: Ticket.

The information we need to have for retrieving a specific ticket is the ticket ID and so in the field element, we map ticket/id. 

Finally, for inbound attributes, we add the requests to create and update a ticket. This information is found in the application specific documentation.

Now the endpoint configuration is complete and you can create your routing rules.