Using the AUTTO API Manager

The API Manager is where you can set up API calls to other applications that do not have direct integrations with AUTTO. This article discusses the API Manager in more detail.

Table of Contents

• Introduction
• The API Manager
• Setting Up OAuth
• Supported API Requests
  • GET Requests
  • POST Requests
  • PUT Requests
  • PATCH Requests
• Creating an API Call
  • To Create an API Call
  • To Add the API URL and Query Parameters
  • To Add OAuth Integration
  • To Add Optional API Headers and Basic Authorisation
  • To Add and Map Responses
  • To Add and Map Payloads (Applicable for POST and PUT calls only)
• Testing the Connection
• Setting a Default API Call
• Deleting an API Call
• Using API Calls in a Workflow

Introduction

Workflows created in AUTTO can integrate with other applications through the Integrations option on the Main Menu. AUTTO directly integrates with the following applications:

• Google Drive
• OneDrive
• Dropbox
• Eversign
• Stripe
• Slack

AUTTO facilitates setting up integrations with Microsoft Dynamics, Salesforce, Slack, and Google APIs, e.g. Gmail, Google Calendar, and Google Docs, among other Google applications, via API Manager Integrations. You can then set API calls to these services from the API Manager. These applications require the OAuth authorization protocol for access to their APIs.

For other applications that do not have direct integrations with AUTTO, you can use the APIs of these applications, if available, to connect them with AUTTO. You also set up these integrations in the API Manager.

NOTE: Familiarity with web applications development is needed when working with APIs.

The API Manager

You can use the API Manager to create GET, POST, PUT, and PATCH calls to APIs for applications that do not have direct integrations with AUTTO. For applications that require OAuth authorization for API access, you can set them up up as an API Manager Integration instead.

Setting Up OAuth

OAuth is an industry standard authorization protocol. Some applications, e.g. Salesforce, Microsoft Dynamics, Hubspot and Xero, require OAuth before you can use their APIs in your applications. AUTTO provides for a way to set up OAuth in the API Manager to facilitate this process.

Before you can use this feature, you will need to set up integrations via API Manager Integrations, which is available from the Integrations option under the Main Menu. For more information, see API Manager Integrations.

Once you have set up your API Manager Integrations, you can set up OAuth to connect to the integration from the AUTTO API Manager. For more information, see To Add OAuth Integration.

NOTE: When using OAuth to authorize your connection with an API, keep in mind that OAuth Scopes limit AUTTO's access to your account and that your access token will be limited to the scopes granted. The authorization server or user can modify the scopes granted to the application compared to what is requested. The Scope is defined when you create the API Manager Integration. For more information on Scopes in OAuth 2.0, click here.

Supported API Calls

You can create HTTP GET, POST, PUT, and PATCH API calls using the AUTTO API Manager.

GET Calls

GET requests retrieve resource representation/information only - they do not modify the retrieved data in any way. GET requests are deemed as safe methods, since they do not change the state of the resource, and idempotent, as multiple identical requests produce the same result every time until another API (POST or PUT) changes the state of the resource on the server.

In contrast to GET requests, POST or PUT requests changes the state of the resource.

POST Calls

POST requests create new subordinate resources, e.g., a file inside a directory or a row in a database table. POST requests create a new resource in a collection of resources.

Ideally, if a resource has been created on the origin server, the server responds with a 201, or Created, code containing an entity describing the request status and referring to the new resource. The response will also often include a header.

When an action performed by the POST method results in an unidentifiable resource, a 200 or 204 response code is expected.

PUT Calls

PUT requests either update an existing resource or, if the resource does not exist, create a new resource (though they may also choose not to create a new one). In case a PUT request creates a new resource, the origin server responds with a 201, or Created, code. If the PUT request modifies an existing resource, a 200 (OK) or 204 (No Content) response codes is sent back to indicate successful completion.

PATCH Calls

PATCH is for partial updates to a resource. That is, you only have to send the fields you are updating. When sending a PATCH request, the only response will be that the call has been successful. You can use a GET after a PATCH to check that the fields have been updated.

In contrast to PATCH, PUT is used to update all the fields in a record while POST is generally only for new records.

Salesforce is an example of an application that supports API PATCH calls. If you want to integrate AUTTO with Salesforce and you need AUTTO to update records in Salesforce, you must set up an API PATCH call to ensure that your workflow will update records in Salesforce.

Creating an API Call

API GET, POST, PUT, and PATCH requests are created using similar procedures in the API Manager.

To Create an API Call

To create an API call:

1. On your Dashboard, click the Main Menu, then API Manager.
2. On the top right of the API Manager, select the appropriate API call type from the list, then click Create. The options are API GET, API POST, API PUT, and API PATCH.
   
   
   
   
3. Enter a name and description for the API call.
   
   

To Add the API URL and Query Parameters

1. Click the API URL button, then enter the API URL on the box. The URL is then displayed under the Technical Summary section.
   
   
   
   
2. Under the Query Parameters section, enter the name and description of the parameter. To add more parameters, click the Add Parameter button and repeat this step until all parameters have been added.
   
   

To add an optional API header or add basic authorisation to the API call, see To Add Optional API Headers and Basic Authorisation. Parameters can be used in an API header. 

NOTE: If you make a mistake adding a query parameter, click the Trash button to the right to delete it.

To Add OAuth Integration

If the API you are connecting to uses OAuth, you can set up its OAuth integration in Main Menu > Integration to allow for more extensive integration capabilities. For more information, see Setting Up OAuth. You can then call that integration from within the AUTTO API Manager.

To use OAuth integration for your API call:

1. Click the Integrations button, then click the Integrations for API Manager button to enable it.
   
   
   
   
2. Select the integration you created earlier from Main Menu > Integrations.

To Add Optional API Headers and Basic Authorisation

If you have not enabled OAuth integration (see To Add OAuth Integration), you can use this procedure to set up basic authorisation for your API call.

NOTE: Parameters (see To Add the API URL and Query Parameters) can be used in an API header.

1. Click the API Header button, then enter the header name and value. To add more headers, click the Add Header button and repeat this step until all headers have been added.
   
   
2. To add basic authorisation to the API call, click Add basic auth, then enter a username and password on the Generate Base64 token window.
   
   

NOTE: When basic authorisation is added, it overrides any authorisation header that you may have added in Step 1.

To Add and Map Responses

1. To add the server responses and map them to AUTTO data types set up in square brackets, click the Response Map button.
   
   
   
   
2. Click Add Response.
   
   
   
   
3. Select the data type that matches the API response from the list.
4. The response is then added to the list of responses on the Response Map. To set up the API response, click the down arrow to its right.
5. Enter the property name and JSON key for the response, adding an optional description if needed.
   
   
6. To set up options for the API response, click the Advanced Options button. Here, you can enable the Regular Expression button, if needed, then enter the regular expression that will be used to extract the retrieved data from the API. You may also enter a default value for the response at this point.

NOTE: Regular expressions (Regex) are a sequence of characters that define a search pattern for input validation. As of August 2020, AUTTO already features improved Regex support.

7. To add and map more responses, repeat Steps 2-6.

NOTE: When mapping server responses to square brackets, use a period to separate information contained within the response. For example, to retrieve a postal code contained in an address response, use address.postcode to map the data to a square bracket.

8. If you are creating a GET request, once you have added all the responses, click Done. The API call is then displayed on the API Manager.

If you are creating a POST or PUT request, you will need to add and map payloads to the API call. For more information, see to To Add and Map Payloads (Applicable for POST and PUT calls only).

To Add and Map Payloads (for POST and PUT calls only)

You will need to add and map AUTTO data types to the simple data types in your POST and PUT API calls. This is to ensure that the payload in your API calls will properly create or update the resources in the other application.

NOTE: If you are creating a GET API call, you will not need to add and map a payload or payloads to the call.

1. To add the API responses and map them to AUTTO data types set up in square brackets, click the Payload Map button.
2. Click Add Payload.
3. Select the data type that matches the API response from the list.
   
   
   
   
4. The response is then added to the list of responses on the Response Map. To set up the API response, click the down arrow to its right.
5. Enter the property name and JSON key for the response, adding an optional description if needed.
   
   
   
   
6. To add and map more responses, repeat Steps 2-5.
7. Once you have added all payloads, click Done. The API call is then displayed on the API Manager.

Testing the Connection

After creating the API call on the API Manager, you can test the connection to see if you have set it up correctly.

 To test the connection:

1. On the API Manager, click the API call with the connection that will be tested.
2. Under the Test API section, enter value/s for the query parameter/s that have been defined under the API URL section (see Adding the API URL and Query Parameters).
   
   
3. Click Test to display the response under the Test Response box. In case of any errors with the call during testing, go back and address them, then test the connection again until there are no more errors. A sample test response, with a 400 error, is seen in the screenshot below.
   
   

Setting a Default API Call

If you have API calls that are used in multiple workflows, you may want to set them up as defaults so that they will appear first on the list of API calls in the Get and/or Send Data actions. You can set as many as four (4) default API calls.

To set an API call as a default:

1. On your Dashboard, click the Main Menu, then API Manager.
2. Click the icon to the top of the API call , then click Set Default.

Deleting an API Call

To delete an API call:

1. On your Dashboard, click the Main Menu, then API Manager.
2. Click the icon to the top of the API call , then click Delete.
3. Click OK to confirm deletion of the API call.

Using API Calls in a Workflow

Once created, you can use GET requests in workflows using the Get Data action. For more information, see Get Data Action.

As for POST, PUT, or PATCH requests, you can use them in workflows using the Send Data action. For more information, see Send Data Action.

For an example of how to use API calls in a workflow, see Getting Started with the AUTTO API.

NOTE: When an API call is used in a workflow, it displays a Lock sign on the API Manager, meaning that any changes to the API call may affect the published workflow and potentially cause problems. In this case, you can only edit the API call by clicking the Lock sign and entering your password on the Unlock editing API call window.