How to implement OutSystems REST HTTP methods that are not built-in

HTTP defines some request methods that show the actions we want to execute. These methods drive the fundamental API interactions that we see day in and day out.

HTTP request methods supported by OutSystems (by default)

The most used HTTP methods are POST, GET, PUT, PATCH, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. They are the ones that by default we use in the OutSystems platform.

  • GET: requests a representation of the specified resource. Requests using GET should only retrieve data.
  • POST: submit an entity to the specified resource, often causing a change in state on the server.
  • PUT: replaces all current representations of the target resource with the request payload.
  • DELETE: deletes the specified resource.
  • PATCH: apply partial modifications to a resource.
PATCHPartial Update/Modify

HTTP request methods NOT supported by OutSystems by default

Out-of-the-box OutSystems does not provide the option to consume an endpoint using the HEAD, CONNECT, OPTIONS, and TRACE methods.

  • HEAD: asks for a response identical to that of a GET request, but without the response body. HEAD requests are useful for checking what a GET request will return before actually making a GET request.
  • CONNECT: establishes a tunnel to the server identified by the target resource.
  • OPTIONS: describes the communication options for the target resource.
  • TRACE: performs a message loop-back test along the path to the target resource.

For the case study we have here we will be consuming a HEAD method. We will consider that the endpoint is the same, although the method is different.

To be able to consume such an API it is required to perform certain actions. But let’s see step by step what we should do.

1. Import the HEAD endpoint as a GET

Here you must notice that the endpoint, URL Path, is the same. But one of the actions is GetCommunicationsGET and the other is GetCountHEAD. The prefix is solely for this example to denote which is going to be used as GET and which is going to be used as HEAD.

2. Add the type to the HEAD corresponding action

You will need to add an extra input parameter, named Type. The Type input will inform which is the method being used. This parameter needs to be added to the request. This will be used in later steps, namely in wrappers for the API methods.

3. Add the OnBeforeRequest to the API

To change the HTTP Method one needs to customize the response. By adding the OnBeforeRequest it is possible to parse the request and check if it is the HEAD method or another method.

To do so you must arrange the OnBeforeRequest REST API Callback by doing this:

  • Set the CustomizedRequest with the Request built by the platform.
  • Check if this is the correct endpoint, i.e. if the URLPath is the one we want to change.
  • If the endpoint is the one we need to change then we search for the Type element in the header, by doing a ListFilter. The Headers are a set of key-value pairs. By searching the key Type we can check its value.
  • In the second conditional IF we finally check the value of that key. If it is “HEAD” then we parse the request corresponding to the GetCount. If not, then it can be one of the other methods, and in that case, we exit.
  • As the last step, we set the HTTPMethod of the CustomisedRequest to “HEAD”, changing its current method.

This is how the OnBeforeRequest should look like:

4. Create Wrappers for the API methods

The methods should be included in the server/service actions. These actions do not need to expose the parameter Type.

So, the wrapper must have its normal input/output and an extra, that is the Type parameter.

Forge component ardoHTTP

There is a Forge component that you can see in the sense of, as they say, “Perform HTTP requests LIKE A BOSS”. It is the ardoHTTP.

It’s a very simple component to use, and for cases where you have to consume a simple API, it can be the component to use. It performs all the major HTTP request types, that is, GET, POST, PUT, DELETE, HEAD. And allows basic authentication. In case you want more elaborate and customized authentication, this won’t be the approach you need.

It is a pretty straightforward component. In some cases, let’s say a GET you might need to deserialize the result. In the HEAD you might not have all the outcomes you want, but in general, it can be what you are looking for.

Thank you note: This post is special because my friend Diogo Carvalho played a key role. As a matter of fact, it would not be possible without him. So, thank you very much Diogo.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s