When you need to retrieve or manipulate information from another system, and that system provides REST APIs for that effect, you can consume a REST API in your application.
Start by looking into the documentation of the REST API you want to use and understand how it works. You will need to gather the following information:
- Base URL
- Security/Authentication requirements
- Methods definition (HTTP Method, URL Path, response format)
In Service Studio you can consume:
- a single REST API method
- all REST API methods described in a Swagger specification file, provided either by entering a URL or by selecting a specification file from the local file system
Each REST API will have their own model of security and authentication process, which may imply the creation of an account, the registration for an API key or the usage of tokens. To consume a REST API in OutSystems you must understand and follow the provider's security model.
Consume one or more REST API Methods of a REST API
After gathering all the information you need from the REST API documentation, do the following to consume one or more methods of that REST API:
In the Logic tab, open the Integrations folder.
Right-click on the REST element and select Consume REST API....
In the displayed dialog, choose Add single method or Add all methods.
A) Add a single method based on example content for the request and/or response. You may need to specify input parameters in the URL and/or a body for manipulation methods like
PUT; the remaining steps of this procedure will walk you through this process.
B) Add all methods of a REST API you want to consume if the API is compliant with the Swagger specification – REST APIs exposed by OutSystems are compliant with this specification.
You can import Swagger specifications either by providing a URL or by selecting a specification file from the local file system. When you import all methods of a REST API you don't have any more steps to follow; the new REST API and its methods will be created under the REST element in the tree.
Fill the information about the Method URL. You can include parameters between braces in the URL for the method's input parameters.
If the REST API you are consuming requires authentication or specific headers, open the Headers/Auth tab and fill the necessary information.
Fill the information about the Request and the Response. The easiest way to do this is to perform a test to the API and use the test result — alternatively, you can add the JSON structure or plain text example directly in the Request and Response fields in the Body tab. Open the Test tab. If you have parameters in your Method URL, you need to insert the parameter values to execute the test:
For manipulation methods, such as
PUT, fill the Request of the Body Content with the corresponding request structure:
Click Test. If the test is successful, you will see the method’s response in the Response area of Test tab. Use that information to fill in the Response in the Body tab by clicking Copy to Response body in the Response area. Leave only the needed fields. For manipulation methods (such as
PUT), do the same for the Request, by pressing Copy to Request body in the Request area:
Usually, the most common fields are obtained this way. To know in full detail all the available fields, check the API documentation.
Check if the Request and Response information is correct in the Body tab and click OK:
At this point, check what OutSystems does automatically for you:
- Creates the REST API
- Creates the REST API Method with the corresponding input and output parameters
- Creates the Structures to hold the corresponding input and output parameters
- Maps the REST Data Types into OutSystems Data Types
Use a REST API Method in your Application
OutSystems translates the methods exposed by a REST API into OutSystems actions, with the same semantics as any action created by you in Service Studio.
You can now use the newly created methods in your application the same way you use the remaining Server Actions:
- Go to the action flow where you want to use the REST API Method.
- In the Logic tab, open the Integrations folder and the REST element.
Open the REST API and drag the REST API Method into your action flow.
Use the method's output parameters as you do for any other action.