Some REST APIs require application authentication. This means that you use a key and a secret to identify your application when executing the service.

For that, first you need to register your application in the service provider to get the key and the secret. This is called creating a service account.

To avoid sending the key and secret back and forth while using services, you use them only once to get an authorization token. With this token your application can have access to the services. To increase security, some services also issue tokens with an expiration time.

The implementation is typically done as follows:

  1. Get the Authorization Token
    1. Look into the API documentation. Understand how you can invoke the REST API method;
    2. Define the REST API and REST API method. Use the information you found in the API documentation;
    3. Understand what is created.
  2. Use the Service
    1. Look into the API documentation. Understand how you can invoke the REST API Method;
    2. Define the REST API and REST API method. Use the information you found in the API documentation;
    3. Understand what is created;
    4. Use the REST API method in your application, with the authorization token attached to it.

Example

Imagine you want to build an application in OutSystems to search for tweets. Twitter provides a REST API with authentication for that effect.

1. Get the Authorization Token

1.1. Look Into the API Documentation

Go to the Twitter API documentation and understand how their REST API works:

Starting with the authentication, you will find that the REST API Method to obtain an authorization token has the following specifications:

To test request/response structures, use the console of the service provider (if any) or a generic console like apigee or cURL.

1.2. Define the REST API and REST API Method

Add the REST API and the REST API Method:

  1. In the Logic layer, expand the 'Integrations' folder;
  2. Right-click on the 'REST' element and select 'Consume REST API...';
  3. In the displayed dialog, choose ADD SINGLE METHOD.
  4. Fill the information about the Method URL: POST and https://api.twitter.com/oauth2/token

1.3. Understand What is Created

Press Ok and the OutSystems Platform does the following for you:

Notice the values in the 'Name' and 'Base URL' properties.

Notice the values in the 'Name', 'URL Path', 'HTTP Method', 'Request Format', and 'Response Format' properties.

Notice the PostTokenResponse structure and its attributes:

Change the name of the REST API to 'TwitterAuthentication'.

To end this setup, set the basic authentication for this REST API:

  1. Go to your service account in the Twitter Application Management website;
  2. Add your application to the list;
  3. Get the key and secret for your application;
  4. Set the key and the secret in the Basic Authentication section of the TwitterAuthentication REST API.

The part of obtaining the authorization token is done.

2. Use the Service

2.1 Look Into the API Documentation

Add the method to list the Box content, check the specifications in the API documentation:

2.2. Define the REST API and REST API Method

Add the REST API and the REST API Method:

  1. In the Logic layer, expand the Integrations folder;
  2. Right-click on the REST element and select 'Consume REST API...';
  3. In the displayed dialog, choose ADD SINGLE METHOD.
  4. Fill the information about the Method URL: GET and https://api.twitter.com/1.1/search/tweets.json?q={SearchString}

Notice the parameter '{SearchString}' in the URL. It originates the input parameter of the REST API Method, which is sent in the URL of the request by default. Learn more About REST API Method Parameters.

2.3. Understand What is Created

Press Ok and the OutSystems Platform does the following for you:

Notice the values in the 'Name' and 'Base URL' properties.

To pass the access token to the service, we will save it to a variable when we call that service (see implementation later).

Create the variable, and set the Authorization header field in the HTTP Headers section accordingly:

Notice the values in the 'Name', 'URL Path', 'HTTP Method', and 'Response Format' properties.

Notice the Status and Search_metadata structures and their attributes:

2.4. Use the REST API Method in Your Application

You can now query tweets on a web screen:

  1. Add input field for the query string and search button;
  2. In the search action:

    1. If there is no authorization token yet:

      1. Use the action to get the token and pass "client_credentials" in the grant_type input parameter;

      2. Put the token returned in the Response in a variable in memory (in a session variable).

    2. Search for tweets.

  1. Use a table records to list the tweets on the screen:
    1. Use a local variable to assign the list of tweets and put it as source of the table records;
    2. Add the columns you want to show.

Publish and open in the browser.

See Also

Retrieve Data using REST | Get User Authorization