HowTo: Access secure REST services defined via API Objects

Official Content
This documentation is valid for:

When you have defined an API object with a security scheme and this scheme has already been configured, it is possible to connect to the service in different ways.

Suppose that an API object has been defined with a security scheme as shown in the article HowTo: Defining an API object with a security scheme.

In addition, the configuration process has been performed in the GAM Backend, as shown in the article HowTo: Configuring the API object security scheme.

Then, you have a Client Id and Client Secret information and you can connect to the server through one of the following three ways:

  1. Using the Launchpad Tool Window.
  2. Using YAML via Postman.
  3. Using the HttpClient data type.

1. Using the LaunchPad Tool Window

To prototype using the Launchpad Tool Window, follow the steps below:

Press F5 to generate the Launchpad Tool Window. Select the APIS Tab and click on Authorize:

SettingthesecurityschemeAPIobject3

A pop-up screen like the one below will open. In that window you have to:

  1. Add the same username and password you used to log in to the GAM Backend.
  2. Select the "Request body" value in the combo box titled "Client credentials location."
  3. Paste in the "Client_id" and "client_secret" fields the data you saved in step 2 of figure 2 in HowTo: Configuring the API object security scheme
  4. Click on the link "Select all" offered in the "Scopes" section.

SettingthesecurityschemeAPIobject4

Finally, you will be able to enter the CustomerId, AccountId, and the AccountPasword to view the customer's account information in the Launchpad:

SettingthesecurityschemeAPIobject5

If you try to get the information of a certain customer, but you have not previously performed the authentication or authorization process, you will get a 401 error with the following message:
{
  "error": {
    "code": "0",
    "message": "This service needs an Authorization Header"
  }
}

2. Using YAML via Postman

In the API object, set the REST Protocol property = True and the Generate OpenAPI interface property = Yes. Next, run the API object by right-clicking on it. By doing this, GeneXus understands that it must generate the YAML file with the security information. Then, you can follow the steps listed in the following articles:

3. Using the HttpClient data type

With GeneXus, you can consume any REST service (generated with GeneXus or not) with a security scheme. In this case, you can use the HttpClient data type

As in the previous case, you can configure the necessary properties and obtain a YAML file with the security information. Then you can use the OpenAPI import tool to import the generated YAML file to a different KB. Consuming a REST Service is also possible by following the steps described in the article Consuming a Rest Service with GeneXus

In any case, it is necessary to create a Procedure object and add the mandatory Authorization header. Use the GetAgentServiceHeader method of GAM object to get the correct one for your use case. You could also do the calling manually using the Access_token GAM Service. So, include in the Procedure source:

&httpclient.AddHeader('Authorization', &access_token)

When you have the token information, you can follow the steps shown in the article HowTo: Develop Secure REST Web Services in GeneXus

See Also

API object security scheme