When consuming REST API Methods, the OutSystems Platform automatically creates Structures that define the Request and Response parameters.

However, the OutSystems Platform first tries to reuse existing structures under the same REST API before creating a new one. This minimizes the number of structures in your application.

When Are Structures Reused?

To reuse structures, the OutSystems Platform compares the structure that is about to be created with existing structures in same REST API. The new structure is created if the following conditions apply to each of the existing structures:

If there is a structure to which none of the above conditions apply, it is then reused to define the Response/Request, instead of creating the new one.

When an existing structure is reused, there might be attributes that need to be added. For example, when half of the attributes matched, the missing half is added to the existing structure by the development environment. This won't have any impact on the methods that are already using the structure.


Following are some examples about each scenario:

Example 1 - The First Structure

When consuming a REST API for the first time, the development environment creates the following:

  1. A new REST API entry:
  2. New structures for the Request and/or Response in the REST API entry on the Data tab. The development environment infers the attributes' data type.

Now, imagine you create a method that changes the Twitter user's account settings, for instance the language. From the result you decide to keep only the language and the use_cookie_personalization parameters.

For this method the following structure is created:

Note that the name of the folder is the name of the REST API (Twitter).

The name of the structure is generated from the HTTP request type (Post), the method name (Settings) and if it is for a Request or Response.

Example 2 - Reusing a Structure For a New Method

After the first structure is created for a REST API, for any further method you add to the same API, the OutSystems platform tries to reuse the existing structure if it is possible.

Imagine that after adding the PostSettings method in the above example, you add the GetSettings method of the same REST API, keeping only some relevant response parameters:

The development environment notices that for this response the structure of the PostSettings method can be reused, as they are very similar. However, some modifications are needed:

Note that the structure is renamed to Settings. This name matches both methods where it is used.

The GetSettings method response had one additional parameter in comparison to the PostSettings, so an additional attribute was added to the structure. Note that the same structure is still in use by the PostSettings method. As a consequence, if you store the response of a PostSettings call in a variable, the additional attribute will get the default value, as the PostSettings method doesn't give any value to it.

Example 3 - Modifying Structures To Reflect Method Modifications

When you modify the request or response example of an existing REST API method, the OutSystems Platform tries to modify the underlying structure to match the changes. If the modification is a minor change, the existing structure gets modified and reused.

Imagine that you need to modify the GetSettings method response to include the 'discoverable_by_email' response parameter:

As the new structure that the modification suggests has only one extra attribute, and three attributes match, more than half of the needed attributes are covered by the existing structure. In this case there is no need to create a new one. The development environment adds the required attribute:

Example 4 - Creating a New Structure

In some situations (type collision or too many differences) the existing structures cannot be reused despite the similarities.

Imagine that you need to add a larger number of parameters to the Response example of the GetSettings method, and to remove one that was already there:

In this case only three of the necessary attributes are covered by the existing structure, which is less than half of the attributes. A new structure called Setting is created, to hold the GetSettings method's Response values:

Note that the earlier structure is not deleted, as it is still in use by the PostSettings method.

See Also

REST Data Types to OutSystems Data Types