VOGO Voice – Knowledge Base

REST API

Estimated reading time: 3 min

Connector Supports: Read/Write

Introduction

API (Application Programming Interface) is the software intermediary that allows programs to communicate with each other based on the set of norms it has outlined. REST (Representational State Transfer) is a software architectural style that defines a set of concepts to be utilized for creating Web services based on the REST Technology. Developers avail this standard set of functions for modeling and accessing an application’s data as interrelated objects and collections.

REST determines how the API should be modeled in order for it to interact with a software component. Furthermore, REST is a hybrid style that offers a set of rules for developers to follow when creating APIs. Rooted in this technology, a REST API connector provides an interface for developers to request data from a specified resource via HTTP protocol such as GET and POST.

The VOGO Voice REST API connector instances provide easy access to CREATE, RETRIEVE, UPDATE, and DELETE data.

Prerequisites

  • Have the REST API Security Essentials.

Anatomy of Settings

Defining Settings values for Add New REST API Account

Name: It refers to the name assigned to the instance of the connector created.

Base URL: Provide the URL of the server or service to which the endpoint path is linked. Typically this is the root of the API service.Root Data Property: The root endpoint or starting point of the API from which a specific part of the data is requested.  This is typically left empty unless you have some object that may look like the following, in this case, we would use “records” to map the results to only be the records array and not just the whole response object.

{

   count: 50,
  records: [{…}, {…}, …]

}

Connector Usage

Now that a connector is established it can now be used within any interaction flow. Each usage of the connector will allow different configurations to retrieve different results. Those settings can be either static or dynamic based on the needs.

Anatomy of Configuration

Defining Configuration Values for REST API Connector

Name: The name assigned to identify the connector linked to a server endpoint. The assigned name is used every time the connector is called to action through the components in the interaction builder platform.
Method:  Choose from the drop-down list the specific HTTP method that corresponds with the type of request made to the server. The methods GET, POST, PUT, DELETE & HEAD correspond to CREATE, READ, UPDATE & DELETE respectively.
Endpoint: Provide the URL to the server route to which access is intended. If this field is left empty, the system will use the Base URL.  The request will concat the Base URL with the endpoint. ie. base = https://myendpoint/api/v1/  and the endpoint is “posts/” then the request would be made to https://myendpoint/api/v1/posts/
Parameters: Enumerate the variable parts of the data using the key-value structure in regard to the REST request specified in the URL. Parameters are typically used in GET requests. Refer to the API of the REST service to determine which parameters to provide if any.
Authorization: Choose the appropriate authentication scheme and furnish right below the authentication credential information for the response being requested. The three types of authentication schemes include Basic Auth, Bearer Token and API key.

  • Bearer tokens are usually generated by the server in response to a login request. This security token is opted for in the Authorization header when sending a request to a protected resource.
  • Basic Auth is a simple authentication scheme built into the HTTP standard that requires a username and password.
  • API Key – API key-based authentication can be sent in two ways, either as part of the query string or in the Header. 
    In the Add to field within the API Key field, choose query params if the API Key is intended to be sent in the query string. The list of key-value pairs included in this section will automatically appear in an additional field titled API key Headers just above in the Parameters section. 

👍 Note: Query params modify request with key-value pairs to serve the purpose of strong validation checks on the server for each request sent across.

If the API key is sent as a request header it will immediately be added to the API Key Headers in the Headers section right below. 
Headers: Offers the provision to provide key-value pairs that carry information pertaining to the request metadata. Headers are included to indicate the format of the request and allowed response.

Body: Specify the content type that is used in the body of the request sent to the server. The given body formats to choose from include none, x-www-form-urlencoded, form-data and raw.
X-www-form-urlencoded: This content type application is chosen when the whole data is sent as a long query string that contains key-value pairs.
Form-data: A webform used to enter data in a key-value pair data structure in order to send it across to the server for processing.
Raw: Provision is allowed to choose from either of the two raw body content-types i.e  Text or JSON (application/javascript).

Caching: To know about caching, click here.

Tags:
Was this article helpful?
Dislike 0
Previous: CARTO
Next: Caching