Define Request

It is the basic definition of the api request. It is used with both connector and authenticator. The connector is a container for requests , that handle the authentication and the execution of a series of requests.

Create a general request

To create an HTTP request to communicate with any Api, you typically need to define the following components:

  1. Request URL : Specify the URL or endpoint you want to send the request to.

  2. Request method : Choose the appropriate HTTP method for your request, such as GET, POST, PUT, DELETE, etc. This determines the action you want to perform on the server.

  3. Request headers : Set any headers required for your request, such as Content-Type, Authorization, or custom headers. Headers provide additional information about the request.

  4. Request body (optional) : If your request requires a payload or data, you can include it in the request body. The body format depends on the specific API or service you are interacting with. It can be JSON, form data, XML, or other formats.

  5. Authentication (if applicable) : If the API or service requires authentication, you may need to include authentication credentials in the headers or request body. The method of authentication depends on the specific authentication mechanism being used.

  6. Send the request : Use an HTTP client library or framework in your preferred programming language to send the request to the server. The library will handle the low-level details of establishing the connection, sending the request, and receiving the response.

  7. Handle the response : Once you receive the response from the server, you can access the response status code, headers, and body. You may need to parse the response body based on its format and extract the relevant data.

Define request in WS project

request form

The description of the fields is explained bellow :

Attribute Description

App

Use Axelor application plugin

Name

The name of the request ( Required)

URL

It can be a sub url of connector or full url of the api request.

Type

Type can be any of GET, POST, PUT, DELETE, PATCH (all are REST api request type)

Payload type

It is a type of data put inside the payload of the request, we can find

Call if

Groovy expression to conditionally call the request, so request will be called only if this expression is true

Repeat if

This is also a groovy expression, if provided it will keep calling the request until expression is true. All requests of a connector with the same ‘Repeat if’ get combined for execution in a loop. For example, to search and download files we have two requests one for search and one for download, if both requests have the same ‘Repeat if’ both will be called in a loop one after another. It is added for the pagination purpose

Headers

Provide here all headers required for the api request call

Payload

It is a key and value a pair of data to be passed a payload of the request. Nested data support is also there

In the payload type we can find those types for using it in your payload request .

Payload type

Description

Form

If the request accepts html form data, just like AOP login request

Json

If the request accepts json data as payload

Xml

If the request accepts xml as data of payload

Text

If the payload is of simple text type

File path

If payload data required a file content but in context if we are providing only file path then this type should be used

File link

f payload required a file content but in context if we have url of file

File text

If payload requests a file content and in context if we have content of file in text format

Stream

If payload required a file content and in context we have a file data in octet stream

Payload | Parameter builder

There are different forms to define the body / payload of the request. For this purpose the payload / parameter builder can form a json or a xml payload or any form type selected.

key value form

In a Json object there is always a key with a value , the value can be an object or simple value or a list . the same for Xml type , the key represents the entry point .

  1. key : Define a Key for the payload.

  2. value : The value of the key , it can be an object or a list or a simple value ( string , int , boolean …​)

  3. List : Specify that the value of the key is a list.

  4. Sub key value : When we want to define the value as a list or an object , we need a new payload builder .

When we don’t select the List checkbox , and the value is null for the payload , that’s mean we the payload is an object with the key name and the value is the Sub key value.

Sub key value

For using the sub key value builder you need to respect some rules to create your form json/xml/text/…​ , there is fourth rules :

  1. Line without key and value : that means the whole line is another object .

  2. Line with empty key and a specified value : this case is correct only if the list option is checked , and that means the list has s value of this line ( not an object )

  3. Line with specified key and a value : that means the line is a simple pair with a key and a value .

  4. Line with empty value and a specified key : that means the line is an object with a key name and the value is another object or a List .

There is the possibility to order the pairs key and values , each payload has a unique sequence , the first payload has a sequence value equals to 0.

Use cases and examples

We define in this section a fourth examples of using the payload builder and building a payload json for any request :

  • Case 1: A pair of a key and a value :

Create a json with a username and password key , the value in this case is admin for both of keys .

key value form

The payload json will be like this :

{
   “password” : “admin”,
   ”username” : ”admin”
}

  • Case 2: Define a key with sub key value ( an empty value ) and with list option selected

Create a Json contains a fields key which is a list of strings .

key value form
key value form

When we selected the list option , that’s mean we want to create a list with the key name, so we need to add the right information in Sub key value The payload json will be like this :

{
    “fields” : [ “name” , ”id” ]
}
you can return back to Sub key value part to understand why we have only "name" and "id" inside the list

  • Case 3: Define a key without value ( an empty value ) and with list option selected

Create a Json contains a fields key which is a list of objects . the list contains only one objects, but you can add new objects as the example shows.

key value form
key value form

When we don’t select the list option , that means we want to create an object with the key name, so we need to add the right information in Sub key value The payload json will be like this :

{
     “list” : [ { “id” : 1, ”name” : ”test” } ]
}

  • Case 4: Define a key without value ( an empty value ) and with list option not selected and sub key value

Create a Json contains a fields key which is an object .

key value form
key value form

When we don’t select the list option , that means we want to create an object with the key name, so we need to add the right information in Sub key value The payload json will be like this :

{
    “data” : { “id” : 1, ”version” : 5 }
}

Header builder

In the context of HTTP requests, headers are additional pieces of information sent by a client (such as a web browser) to a server or by a server to a client. Headers provide metadata about the request or the response and help facilitate communication between the two parties.

In the Header Builder you can select from a list of a common headers the appropriate values .

header builder form