When you need to create, change,
or delete information in another system, and that system provides REST
APIs for that effect, use a
to integrate and manipulate data.
Typically, there are some steps you
always take when adding a REST API method:
- Look into the API documentation. Understand how you can invoke
the REST API method;
- Define the REST API and REST API method. Use the information you
found in the API documentation;
- Understand what is created;
- Use the REST API method in your application.
Imagine you have an external system
for managing tickets (Zendesk) and an application in OutSystems that lists
tickets from there. However, now you need to create tickets. Zendesk provides
a REST API for that effect.
1. Look Into the API Documentation
Go to the Zendesk API documentation
and understand how their REST API works.
You will find that the REST API Method
to create tickets has the following specifications:
- Requires an account in Zenddesk. In this
example, it defines the following base
URL for the REST service: https://osacademy.zendesk.com
- The REST service requires application authentication;
- The REST API method is defined as follows:
- URL Path: /api/v2/tickets.json
- Request and
Response: the JSON structure
we want to use is:
2. Define the REST API and REST API Method
Add the a new method to the REST API:
- In the Logic layer, expand the Integrations folder;
- Right-click on the REST element and select 'Add REST API Method...';
- Fill the information about the Method URL: POST
- Make sure you put your
credentials for Zendesk, in
the Headers/Auth tab;
- Go to the Test tab, fill
the Request of the Body Content, and press Test;
- In the Request tab, press
COPY TO REQUEST BODY;
- Go back to the Test tab,
do the same in Response tab, and leave only the fields we need:
Normally, the most common fields are obtained this way. To know in full
detail all the available fields, check the API documentation.
3. Understand What is Created
Press Ok and the OutSystems Platform does the following for you:
Notice the values in the Name, URL Path,
HTTP Method, Request Format, and Response Format\ properties.
- Creates a Structure
that is the data type of the input parameter (request).
Notice the Ticket
structure and its attributes:
- Compare with the JSON of the request;
- Ticket is used in the
The Request input parameter uses this structure as its data type.
- The Response output parameter has the data type set to the
Check the existing Ticket structure
and its attributes. Compare it with the JSON of the response.
The REST API requires authentication. However, it is already set, in
the Basic Authentication section.
You may change the values that were set by default at any time. For
example, change the Name of the PostTickets REST API Method to CreateTicket.
Before creating the web
screen to create tickets, you should adjust the attributes of the
structure that was created, as it will have impact on the screen design:
- Subject length: 150;
- Subject and Priority are mandatory.
- Name length: 150;
- Email data type: Email;
- Email length: 150.
- Name and Email are mandatory.
4. Use the REST API Method in Your Application
Now, design the web screen:
- Use a form
to get the ticket information:
- Set the CreateTicketRequest structure as source record;
- Add the input fields.
- Use a button
with a screen
action to create the ticket, using the CreateTicket REST API method.
Publish and open
in the browser.
Create a new ticket.
Using the web screen to list tickets, you can see that the ticket was
Retrieve Data using REST