Incoming REST Webservices

ADITO allows processes to be exposed as RESTful web services, enabling external clients to interact with ADITO functionality via standard HTTP methods. This document outlines how to configure such REST web services, handle incoming requests, and format responses according to ADITO's conventions.

---

Configuring the REST Web Service Process

To create a REST web service in ADITO:

1. In the project tree, right-click the process node and select New.
2. Name the process appropriately, e.g., myWebservice_rest.
3. Set the following properties in the process configuration:

Property	Description
publishAsWebservice	Enable this to publish the process as a web service.
style	Set to REST.
restAcceptedMimeType	MIME types accepted by the REST web service. Multiple types can be specified as a comma-separated list, e.g., text/plain, multipart/form-data, application/json.
restDeliveredMimeType	MIME type returned by the REST web service, e.g., text/plain.
loginTypeId	Set to "login" to require username and password authentication.
restrictedRoles	Specify roles that are not allowed to log in to the web service.
enableNestedRequests	Boolean (default false). If true, nested resource requests are accepted (see Nested Resource Requests).

REST Web Service URL Path

The REST web service is accessible at:

http://<adito-server>:<port>/services/rest/<process_name>

For example:

http://aditoserver:8080/services/rest/myWebservice_rest

---

REST Method Handlers

Each HTTP method corresponds to a specific function name in the process script. When the web service is called with a given HTTP method, the corresponding function is invoked automatically.

HTTP Method	Function Name
GET	restget
POST	restpost
PUT	restput
DELETE	restdelete
PATCH	restpatch
OPTIONS	restoptions

---

Example: Handling a GET Request

function restget(requestJson) {
    // Log the incoming GET request
    logging.log("*** Incoming REST GET request ***");

    // Parse the JSON request string to an object
    var request = JSON.parse(requestJson);

    // Set the response body
    request.response.body = "Webservice is operational";

    // Return the updated request object as a JSON string
    return JSON.stringify(request);
}

info

When calling this GET web service from a browser or REST client, the response will include the body "Webservice is operational".

---

Example: Handling a POST Request

import { logging } from "@aditosoftware/jdito-types";

function restpost(requestJson) {
    // Parse the incoming JSON request
    var request = JSON.parse(requestJson);

    logging.log("*** Incoming REST POST request ***\n" + request.body);

    // Set HTTP status code and response body
    request.response.httpStatusCode = 200;
    request.response.body = "OK";

    // Return the response as a JSON string
    return JSON.stringify(request);
}

---

Structure of the Request Object

The REST handler functions receive a JSON string representing the request object with the following structure:

{
  "uri": "/myWebservice_rest",          // Request URI (includes nested path if enabled)
  "query": {                           // Query parameters as key-value pairs
    "param1": "value1",
    "param2": "value2"
  },
  "header": {                          // HTTP request headers
    "Content-Type": "application/json",
    "X-Adito-trace": "trace-id-value"
  },
  "body": "<RequestBody>",             // Request body as a string
  "response": {                       // Object to be populated for the response
    "httpStatusCode": 0,
    "body": "",
    "header": {}
  }
}

---

Constructing the Response Object

The response must be returned as a JSON string with at least:

• response.httpStatusCode: HTTP status code (e.g., 200 for success)
• response.body: Response content (e.g., "OK" or JSON data)

Example:

function restpost(requestJson) {
    let request = JSON.parse(requestJson);

    request.response.httpStatusCode = 200;
    request.response.body = "OK";

    return JSON.stringify(request);
}

---

Adding Response Headers

Additional metadata can be sent via response headers by populating the response.header object:

function restget(requestJson) {
    let request = JSON.parse(requestJson);

    // Set response status and body
    request.response.httpStatusCode = 200;
    request.response.body = JSON.stringify({ message: "Success" });

    // Initialize response headers
    request.response.header = {};
    request.response.header["Content-Type"] = "application/json; charset=utf-8";
    request.response.header["Set-Cookie"] = "sessionId=abc123; Max-Age=3600";
    request.response.header["Location"] = "/products/";
    request.response.header["Content-Disposition"] = "attachment; filename=\"report.pdf\"";
    request.response.header["Cache-Control"] = "max-age=86400, must-revalidate";

    // ETag header examples:
    request.response.header["ETag"] = '"12345"'; // strong validator
    // or weak validator using template literals:
    let etagValue = "12345";
    request.response.header["etag"] = `W/"${etagValue}"`;

    return JSON.stringify(request);
}

Supported Response Headers

Header Name	Description	Since ADITO Version
Accept-Ranges	Specifies if range requests are supported. Value can be either "bytes" or "none"	2025.1.1
Cache-Control	Controls caching behavior in browsers and proxies.	2024.2.1
Content-Disposition	Indicates if content should be displayed inline or downloaded as an attachment.	2025.1.1
Content-Encoding	The encodings that are applied to the content.	2025.1.1
Content-Language	Describes the language intended for the targeted audience.	2025.1.1
Content-Length	The size of the message body in bytes.	2025.1.1
Content-Location	Indicates an alternate location for the returned data.	2025.1.1
Content-Range	Indicates the relative position of the delivered content in response to a range request.	2025.1.1
Content-Type	Specifies the media type of the response body.	Any
ETag	Identifies a specific version of a resource for caching and concurrency control.	2024.2.1
Expires	Contains the date/time after which the response is considered expired in the context of HTTP caching.	2025.1.1
Last-Modified	Contains a date and time when the origin server believes the resource was last modified.	2025.1.1
Location	Specifies the target URL for redirection (used with 3xx status codes).	Any
Retry-After	Indicates how long the user agent should wait before making a follow-up request.	2025.1.1
Set-Cookie	Used to send cookies from the server to the client.	2024.2.1
Vary	Describes parts of the request that influenced the content of the response it occurs in.	2025.1.1
Custom Headers	You can also set custom headers, e.g., "X-Custom-Header": "value".	Any

info

ADITO automatically adds the header X-Adito-trace containing a TraceID for request correlation and debugging. If the incoming request includes this header, its value is preserved in the response; otherwise, a new TraceID is generated.

---

Nested Resource Requests

The boolean property enableNestedRequests controls whether the web service accepts nested resource paths beyond the main process name.

When enableNestedRequests is true (default: false)

• The web service accepts URLs with additional path segments after the process name.
• The full path starting from the main resource is available in the request object's uri property.
• Examples of valid URLs:

/services/rest/my_process_ws/
/services/rest/my_process_ws/this/and/that/35/entry
/services/rest/my_process_ws/organisations/reviewed/

Example uri value in the request object:

{
  "uri": "/my_process_ws/organisations/reviewed/",
  "query": { "param": "value" },
  ...
}

When enableNestedRequests is false (default)

• Nested paths after the main process name are not allowed.
• Any trailing slash or additional path segments cause a 404 Not Found error.
• Valid URLs include only:

/services/rest/my_process_ws
/services/rest/my_process_ws?param=value

Summary Examples

enableNestedRequests	URL	Behavior
false	/services/rest/vcard_delivery_ws	Executes process vcard_delivery_ws
false	/services/rest/vcard_delivery_ws/3fc7e	Returns 404 Not Found
true	/services/rest/vcard_delivery_ws	Executes process vcard_delivery_ws
true	/services/rest/vcard_delivery_ws/3fc7e	Executes process; uri = /vcard_delivery_ws/3fc7e
true	/services/rest/vcard_delivery_ws/persons	Executes process; uri = /vcard_delivery_ws/persons

---

Parallel Execution

• Web service calls in ADITO are processed in parallel. Sequential execution is not supported.

---

Additional Notes

• Ensure that the URLs do not contain a trailing slash unless nested requests are enabled. For example:

  • GET /services/rest/my_process fetches the resource my_process.
  • GET /services/rest/my_process/ (with trailing slash) fetches all elements under my_process only if nested requests are enabled.

• Always provide a Content-Type header in the request matching the accepted MIME types configured in the process.

---

References

• HTTP Status Codes
• MDN Web Docs: HTTP Headers
• MDN Web Docs: Template Literals