Entities as REST Web Services

Entities as REST Web Services in ADITO enable you to expose Entity data as RESTful web services within a specific Context. This feature allows external systems to interact with ADITO entities—reading, creating, updating, and deleting data—using standard REST protocols. Each Context can provide any number of Entity web services, each tailored to deliver or process specific fields or data structures. This capability is available starting from ADITO version 2020.2, and is essential for integrating ADITO with other applications or for building custom data-driven workflows.

info

Use Case:
Entity web services are ideal for scenarios where you need programmatic access to ADITO data models, such as integrating with external CRMs, ERP systems, or custom business applications.

---

Creating an Entity Web Service

To create an Entity web service in ADITO:

1. Open the Context node in the project tree.
2. Right-click the desired Context and select New.
3. In the dialog, enter a unique name and select the type webservice.

Figure: Creating a new Entity web service

tip

Naming Convention:
Use a unique and descriptive name for your web service data model. Recommended schemes:

• <ContextName>_webservice (if only one web service is used for the Entity, e.g., Organization_webservice)
• <ContextName>_<Purpose>_webservice (if multiple web services per Entity, e.g., Organization_Address_management_webservice)

Required Properties

After creation, configure the following mandatory properties for the web service:

Figure: Entity web service properties

Property	Description
webserviceMethods	Specifies which REST methods are available. Figure: Webservice methods
writeProvider	Selects the Entity provider used for creating, updating, and deleting data.
readProvider	Selects the Entity provider used for reading data.
loginTypeId	Controls which login types are supported. Options are drawn from instance configuration. - internal.none: Anonymous access - internal.default: Username and password required
jditoWebserviceUser	Specifies a user with the INTERNAL_WEBSERVICE role. This user is used for JDito script execution and, if enabled, for authentication.

warning

The web service name must be unique within the project and must not conflict with other data models.

---

Defining Data Provided and Processed by the Web Service

Once the web service is created, determine which data it will process:

Figure: Selecting fields and Consumers for the web service

1. In the editor, the left column displays all EntityFields and Consumers in a tree structure.
2. Expand Consumers to view their fields.
3. Select fields and add them to the right column using the + button.
4. Remove fields from the right column with the - button.
5. Selecting fields of a Consumer will also add the Consumer node to the right column.

info

Only fields and Consumers added to the right column will be available through the Entity web service.

After configuration, deploy the web service. Deployment typically activates it immediately. If not, clear the cache manually via the manager.

---

Accessing the Entity Web Service

Entity web services are accessed similarly to other REST web services in ADITO:

Base URL format:

https://<host>:<port>/services/rest/<webserviceName>

Example:
https://localhost:8443/services/rest/Organization_webservice

Endpoint Structure and Methods

warning

URLs are case-sensitive. Use exact names as defined in the ADITO Designer for web service and Consumer names.

URL Pattern	Methods	Description
/services/rest/<webserviceName>	GET, POST	GET: Returns all Entity records. POST: Creates a new record.
/services/rest/<webserviceName>/<Entity_UID>	GET, PUT, DELETE, PATCH	GET: Returns the record by Entity_UID. PUT: Creates/replaces the record by Entity_UID. DELETE: Deletes the record. PATCH: Updates the record.
/services/rest/<webserviceName>/<Entity_UID>/<consumerName>	GET, POST	GET: Returns all Consumer records for the Entity. POST: Creates a Consumer record for the Entity.
/services/rest/<webserviceName>/<Entity_UID>/<consumerName>/<consumer_UID>	GET, PUT, DELETE, PATCH	GET: Returns the Consumer record. PUT: Creates/links the Consumer record. DELETE: Deletes the Consumer record. PATCH: Updates the Consumer record.

info

The OPTIONS method is supported for all endpoints and returns allowed REST methods in the Allowed header.

warning

If a record with the given ID exists, a PUT request will completely overwrite it.

Consumer chains can be extended arbitrarily by appending further Consumer names and UIDs.

---

Query Parameters

You can configure web service calls using query parameters appended to the endpoint URL:

Syntax:
<endpoint>?param1=value1&param2=value2

Supported Parameters

• fields
  Limits the fields returned or written. Supports nested fields (e.g., fields=entityField1,Consumer1.consumerField1). To include all fields of a Consumer: fields=Consumer1.

• excludefields
  Excludes specified fields from the response (same syntax as fields).

• count
  Limits the number of records returned (for paging).

• startrow
  Sets the starting row index (for paging).

• search
  Base64-encoded string for filtering records.

• applyRecordSorting
  Controls sorting:

  • FULL: Applies Entity sorting.
  • NONE: Disables sorting (default).

• Entity Parameters
  Custom parameters in the format:
  entityParams[YourParam_param]=YourParamValue

Example:

https://mycustomer-qs.qs.adito.cloud/services/rest/M_AttributeRelations_webservice?entityParams[ObjectRowId_param]=PROP_42738&entityParams[ObjectType_param]=Property&count=1&startrow=0

Paging Example

To retrieve paged results:

https://localhost:8443/services/rest/Organization_webservice?count=100&startrow=0

Returns the first 100 records.
For the next page:

https://localhost:8443/services/rest/Organization_webservice?count=100&startrow=100

---

Response Format

All REST methods (except OPTIONS) return processed data in application/json format. The response is either:

• An array of objects (for collection endpoints)
• A single object (for record endpoints)

Example: Get all company records

[
  {
    "CUSTOMERCODE": "3469",
    "CONTACTID": "449080f6-b714-4189-a261-37439d0d4010",
    "ORGANISATIONID": "756662b5-f5e4-479c-8d97-abd6a395bd79",
    "NAME": "Aquire GmbH",
    "Addresses": [
      {
        "ZIP": "93055",
        "COUNTRY": "EN",
        "CITY": "Regensburg",
        "ADDRESS": "Blumenstraße",
        "ADDRESSID": "ea50cb02-7d4d-433d-9cd3-c262d5a0bb27",
        "STATE": "Bavaria",
        "BUILDINGNO": "11"
      }
    ]
  },
  {
    "CUSTOMERCODE": "3666",
    "CONTACTID": "019651a4-503e-4e06-aefd-e7e631bf3144",
    "ORGANISATIONID": "97b66b3c-a9f5-4dc4-902e-850d69973d1d",
    "NAME": "Bucher Group of Companies",
    "Addresses": [
      {
        "ZIP": "22765",
        "COUNTRY": "EN",
        "CITY": "Hamburg",
        "ADDRESS": "Julius-Leber-Strasse",
        "ADDRESSID": "e1aef1b7-569b-46be-bc50-f02332a42ef1",
        "STATE": "Hamburg",
        "BUILDINGNO": "5"
      }
    ]
  }
]

Example: Get a single company record

{
  "CUSTOMERCODE": "3666",
  "CONTACTID": "019651a4-503e-4e06-aefd-e7e631bf3144",
  "ORGANISATIONID": "97b66b3c-a9f5-4dc4-902e-850d69973d1d",
  "NAME": "Bucher Group of Companies",
  "Addresses": [
    {
      "ZIP": "22765",
      "COUNTRY": "DE",
      "CITY": "Hamburg",
      "ADDRESS": "Julius-Leber-Strasse",
      "ADDRESSID": "e1aef1b7-569b-46be-bc50-f02332a42ef1",
      "STATE": "Hamburg",
      "BUILDINGNO": "5"
    }
  ]
}

---

Creating and Editing Data

To write data, send a JSON object in the request body that matches the structure received when reading data. The expected payload depends on the endpoint:

• Collection endpoints: Array of objects
• Single-record endpoints: Single object

info

ID fields do not need to be set when creating new records. ADITO generates IDs and returns them in the response.

Creating a Record (POST)

ID fields do not have to be set when creating new data. The system will generate IDs automatically and include them in the response if they are part of the configured web service fields.

The request must contain the header "Content-Type: application/json", otherwise ADITO will reject the request.

Endpoint:
POST /services/rest/Organization_webservice

Headers:
Content-Type: application/json

Request Body:

[
  {
    "CUSTOMERCODE": "3399",
    "NAME": "TEST GROUP OF COMPANIES",
    "Addresses": [
      {
        "ZIP": "22765",
        "COUNTRY": "DE",
        "CITY": "Hamburg",
        "ADDRESS": "Julius-Leber-Straße",
        "STATE": "Hamburg",
        "BUILDINGNO": "77"
      }
    ]
  }
]

Response:

[
  {
    "CUSTOMERCODE": "3399",
    "CONTACTID": "894015a6-31de-4564-918b-6b652b6b2b29",
    "ORGANISATIONID": "d72ae8ac-5237-483e-9d72-c95c72fe6f8d",
    "NAME": "TEST GROUP OF COMPANIES",
    "Addresses": [
      {
        "ZIP": "22765",
        "COUNTRY": "DE",
        "CITY": "Hamburg",
        "ADDRESS": "Julius-Leber-Strasse",
        "ADDRESSID": "37e806d7-e62a-47e0-bfa9-820d5f74ee3b",
        "STATE": "Hamburg",
        "CONTACT_ID": "894015a6-31de-4564-918b-6b652b6b2b29",
        "BUILDINGNO": "49"
      }
    ]
  }
]

Editing an Existing Record (PATCH)

Endpoint:
PATCH /services/rest/Organization_webservice/019651a4-503e-4e06-aefd-e7e631bf3144

Request Body:

{
  "CUSTOMERCODE": "558899",
  "NAME": "My Group of Companies"
}

Response:

[
  {
    "CUSTOMERCODE": "558899",
    "CONTACTID": "019651a4-503e-4e06-aefd-e7e631bf3144",
    "ORGANISATIONID": "97b66b3c-a9f5-4dc4-902e-850d69973d1d",
    "NAME": "My Group of Companies",
    "Addresses": [
      {
        "ZIP": "22765",
        "COUNTRY": "EN",
        "CITY": "Hamburg",
        "ADDRESS": "Julius-Leber-Strasse",
        "ADDRESSID": "ab59a1c8-9bcb-4dc7-9c8d-dc8b3d743caf",
        "STATE": "Hamburg",
        "CONTACT_ID": "019651a4-503e-4e06-aefd-e7e631bf3144",
        "BUILDINGNO": "666"
      }
    ]
  }
]

---

Value List Validation

warning

When writing data via the Entity web service, no validation is performed against value lists that restrict EntityField values (e.g., via dropDownProcess or Consumer). Values are written as provided, even if not in the value list.
If validation is required, implement it using the EntityField’s onValidation process.