Knowledge Base

Get up and running with TERMINALFOUR Web API

Last Modified:
01 Apr 2020
User Level:
System Administrator

Changes were introduced to the /about service and the naming of access tokens in v8.2.8 and v8.3 respectively. 
If you're running an older version, have a look at the older version of this article - 8.2.8 here and 8.3 here.

This is the first in a series of articles we are writing on getting up and running with the Web Services API.

With Terminalfour’s Web Services API, you can view and edit Sections, content and assets without logging into the interface. This takes the possibilities of what can be done with Terminalfour beyond the features offered in the product alone. With the Web Services API, you can integrate Terminalfour with your own or other services in a custom web or native mobile application.

The full Web Services API reference docs are available here

The purpose of this article is to let you connect to your Terminalfour instance and using a GET request and view the "About" details of your instance. In future articles, we'll take this further by using requests to edit content, assets and Sections and then look at creating our own requests in NodeJS.

To get up and running, we’re going to use Postman, a free application that lets you test and develop Web APIs, so to follow along you should download and install this. All screengrabs in this article are from Postman v7.2.0

To follow along with this you should have a user-level of Administrator.

We've also created a collection of requests for you to download and follow along here. 

Postman Environment Setup

When using Postman, you’ll first set up an Environment. This is a set of key/value pairs we’ll initially populate with just the URL of our instance. The advantage of using Environments is that we can move between instances without changing our requests – so we could test our requests on a local or test instance and then, by just switching the Environment context, can use those same requests on our live instance.

To set up the Environment, select the cog icon on the upper right-hand side of the interface:

Screenshot of the Postman Environment settings button

From the window that appears select the orange Add button.

The first variable name we are going to set is 'url' and both the Initial and Current Values are the url for your Terminalfour instance with an /rs (RESTful API) appended to it.

The second variable we are going to need is 'apikey'. This is the Terminalfour API Key that you generated above.

Adding an Environment to Postman with a URL and API Key

Once that’s done, hit Add or Update and close the Manage Environments window.

Before you go ahead, make sure that you select the Environment you just created from the Environment drop-down in the top right of the interface.

Now, we want to import the Collection of Terminalfour requests that you’ve downloaded. These are a set of pre-written requests we’ve created to help you get familiar with the Web API. In Postman go File > Import and select the collection file.

On the left, in the Collections tab, you’ll see an organized folder structure of requests. The first one we are going to use is getProfile. This request is in the root of the collection and outside of the other folders.

When we select the Profile request the HTTP Request Selection Box will show GET as the request type because the request is just reading the resource.

Postman screen with getProfile request response

When you are ready, hit send and if your instance url and API key are valid, Terminalfour should respond with a 200 OK response containing the details of the currently authenticated user.

If you open the Headers tab of the request and uncollapse the "Temporary Headers" accordion, you will see that postman has submitted your APIKey along with the request in an "Authorization" header.

  • The Web Services API Collection (the root ‘folder’ of all the requests) has its Authorization setting set to use API Key Authorization.
  • The default Authorization behavior for all the requests in the collection is to Inherit from the parent collection.
  • Unless you specify an authorization type in the Authorization tab of a request, the request will use the authorization method defined at the collection level.
  • To reveal the authorization settings of the parent collection:
    • Right-click on the Web Services API Collection and choose edit
    • Navigate to the Authorization tab
    • You will see that the type is set to use ‘API Key’, the header key is set to 'Authorization' and the value is set to the variable to which we assigned the API Key you generated in Terminalfour.

Now that we've successfully connected, let's create our own request. We want to create one that will return information about our Terminalfour instance.

There's already a request that will do that but let's create our own. To stay organized, you can create a subfolder in the Web Services API Collection in Postman. You can call this folder 'Custom Requests'.

Screenshot of the add Collection folder option in Postman

In the new folder, add a request. This one is an About request so you can call it 'About':

Screenshot of the Add Request option in Postman

In the URL Input field add the url variable that comes from our Environment settings (variables in Postman are enclosed in double curly brackets) followed by the name of the resource we are requesting. In this case, it's /about/meta.

Since version 8.3.1, a single /about service is no longer used. 
 if this is relevant to you.

Hitting Send will return a JSON output with Terminalfour instance details:

Screenshot of the /about/meta API output in Postman

  

 

That's it! In this article, we've used Postman to get acquainted with the Terminalfour Web Services API. We've looked at connecting and authenticating and how to return details about the Terminalfour instance.

In the next article, we'll look at using the Web API to add and edit Sections in Terminalfour.

Back to top

Files

API Web Services API Postman Collection