There are different ways to integrate one system or application with another. Using an API (Application Programming Interface) is one such way. This allows different systems to communicate with one another based upon a set of predefined rules and methods.
One way is to build this in your favourite language by hiring a Ruby or Python developer, or turn your attention to a low-code development platform. Tools such as Linx can lighten your load and deal with most of the complexity for you, leaving you with only needing a basic understanding of how API’s work.
So how do API’s work?
There are a couple of basic, but important concepts that form the basis of an understanding of API’s. To get us started, let’s look at these:
In a nutshell, it all comes together like this; To work with (“consume”) an API, an application (also referred to as ‘client’) must send a request message that indicates what the application wants to do (e.g. GET or POST specific details) to an API endpoint. The application will be authenticated before a successful connection can be established. Once the connection is established, and the request message is processed, the application will receive a response message.
Do the following:
Before you even start, determine why you want to integrate with the other system:
- your business requirements will determine which operations you will perform on the other system:
- you may for example want to read (GET), create (POST), update (PUT), or delete data
Most API’s have an extensive API Reference published, which you need to go through in order to use the API. Look for the API Reference and understand how the specific API handles authentication and data. When you know why you want to integrate, and how to use the API, do this:
- by providing connection details for the API endpoint
2. Be authenticated
- by providing your user authentication details, if required
3. Send a request
- by using a specific method, e.g. GET (to retrieve data), POST (to add or create new data), PUT (to update data), or DELETE (to delete data)
- to a specific URL and path
- by including relevant input data via e.g. Query parameters, header or body details
4. Handle response
- by receiving the requested data, as well as success or failure responses
- by processing the response data in your application (e.g. in your Linx solution) to achieve your solution’s overall goal. Linx supports responses in JSON and XML formats and makes it easy to handle the response data in any of the more than 35 pre-packaged Linx plugins containing literally hundreds of functions, types and services.
API specifications: SOAP and REST
Let’s now expand on our basic understanding of endpoints, authentication, requests and responses, by looking at API specifications. The goal of API specifications is to standardize the exchange of data. Standardization makes it possible for diverse systems, written in different programming languages and potentially running on different operating systems, or using different technologies, to communicate with each other seamlessly.
The implication is that when you consume an API, the specification will determine how you will connect, authenticate, send a request and receive a response. Linx supports SOAP (Simple Object Access Protocol) and REST (Representational State Transfer) API specifications to guide you through the process of consuming API’s in your process flows, and to decrease the amount of code you would normally require for an API integration project.
Further reading: Using REST to call SOAP services
Using Linx for your API integrations
In Linx you can integrate to API’s by using the functions of one of these plugins:
- The SOAP or REST plugins, specifically the CallSOAPWebService or CallRESTEndpoint functions.
- The Linx plugins that were developed to simplify the integration to specific systems, e.g. various Amazon Web Services plugins (including S3, EC2, SNS, SQS, CloudTrail), Google Drive, Google Sheets, Azure Storage, Xero and QuickBooks.
How to use CallSOAPWebService
- The WSDL of the Service you want to call
- The method to call in the web service
- The Service URL to use when making the SOAP call
- Authentication details
How to use CallRESTEndpoint
You will need the details of:
- Full URL for the request
- Method type to use in the request (e.g. GET, POST, PUT, DELETE)
- Authentication details
- Request details (how to send request data and what data to send)
- Query string (parameters to send with request)
- Header details
- Body details
- Response output type
How to use API-specific plugins
Third party APIs require you to register accounts with them, set up specific app details, and create authentication or connection details for use when making a call to that API. When these prerequisite steps have been performed, using Linx to programmatically integrate to the 3rd party API becomes a breeze.
As an example, let’s look at the steps for integrating to Google Drive:
- Add the Google Drive plugin to your Solution (it’s literally a click of a button).
- From the Google Drive plugin, drag & drop your required Function (e.g. DeleteFile) onto your solution’s design canvas.
- Provide your Google API connection details.
- Set the properties for the selected Function (e.g. in the case of DeleteFile, set the FileID property).