What are REST endpoints and how to configure them

[Kenny]

Novulo REST Endpoints.

This post will contain all information required for setting up a novulo REST endpoint from within the application.

Requirements.

In order to configure REST endpoints you will need the following components:

• M8465 Novulo Data and processes for REST HV
• M8737 Novulo Datadefinities

Different endpoint types.

M8465 introduces two different types of endpoints.

• REST data definitions
  A REST data definition basically opens a data definition to the world. Anyone that knows the URL and has credentials can retrieve the data generated by the data definition. Typically used for a GET.
• REST Processes
  A REST process allows another application or an entity outside of the application to trigger a process within the application. Typically used for POST, PUT, PATCH, DELETE.

How to configure a REST data definition.

1. Create a data definition. For more information on how to create a data definition see Data definitions. When creating this data definition pay extra attention to which data and how much data you will be opening to the world. Think about the following:

• Is the record type sensitive or does it contain sensitive data?
• Do we limit the amount of records with one or multiple parameters?
• Do we make sure that certain records can never be retrieved from the application even if the parameter asks for that record? (for example we have an API which can generate a list of users in a specific group, make sure we never allow for retrieving the admin group.)

2. Go to settings → REST data definitions and create a new record. Give your REST data definition endpoint a name, link the data definition from step 1 and choose a path. This path will be part of your final URL.
3. By default the service authentication type will be set to authorization. This can be changed to impersonation in order to expose an endpoint to anyone. Carefull with this option as you likely do not want just anyone to retreive data from your application. In this case make sure you fill in a valid user.
4. Make sure to generate your REST data definition parameters. Note that this step will be required for most use cases but may be skipped if your data definition does not use a parameter.’

How to configure a REST proces.

!Note: There is currently a known issue in the REST processes when using the mixed datatype. You will have to use a workaround, see the bottom of this post.

1. Create or find a process action definition to use. For more information on how to create a proces action definition, see this post.
2. Go to settings → REST processes and create a new record. Select the proces action definition, method and REST path. This path will be part of your final URL. When saving the record the parameters and return values are automatically generated.
3. When setting up a REST proces endpoint you will have to determine for each proces parameter if you expect the request to:

• Use your process parameters 1-on-1
  For example proces parameter “product identifier” with datatype int:

{“product identifier”: 3}

Resulting in a parameter “products” of type int: int:load(3)

• Let the application translate the incoming JSON to the process parameters.
  For example proces parameter record with datatype mixed which on id 0 has to input products:getnull and on any positive integer has to return a product with external identifier equal to the incoming JSON.

{“product identifier”: 0}

Resulting in a parameter “products” of type products: products:getnull()

{“product identifier”: 29321039}

Resulting in a parameter “products” of type products: products:load(213)

• Use a combination of the above options.

Using the proces parameter 1-on-1.

This option requires no additional changes. The parameter type should remain “body”.

Let the application translate incoming JSON to the process parameters.

1. For this option you will modify the proces parameter type from “body” to “Expression”.
   
   
   
   If you want to use factors from the request in the expression continue with step 2, this is not mandatory however like in the example above where the expression should always result in an empty activity.
2. Create new REST proces parameters for each factor that will be used for providing the initial proces parameter with information. These new REST proces parameters will need to be set to “body”. Check the “required” box.
3. Use %name as a placeholder in the expression of the initial proces parameter.

If we for example want to acomplish the following:

We could do this by adding the following 2 rest processes

How to call a REST endpoint.

• URL: the URL of your endpoint will always be the URL of your application minus “default.aspx” + “rest/” + path.
  For example:

• Authentication: “basic”. The username and password combination is the same as the username and password used for logging into the application. Note that if impersonation was chosen, authentication can be set to “none”.
  

  

• Parameters: You can simply fill in the parameters in the request, these will be passed on to the data definition.
  

  

• Body: When calling a rest process your body should contain the parameters inside of a JSON like this

{
	"input_value_1": "string",
	"input_value_2": 3,
}

Workaround datatype mixed

As mentioned before there is a known issue regarding the datatype mixed. You will have to use the Let the application translate incoming JSON to the process parameters. option even if the JSON would supply the exact value you need and make sure you turn on the “custom response” option.