Use a DataObjectHandler

How the DOH works

At runtime, when a service endpoint is called, the DOH transforms the HTTP request into an ABL object and invokes the associated ABL class or procedure. It also transforms the output from the ABL class or procedure into an HTTP response.

Should I use a user-defined WebHandler, the DOH or a mapped REST service?

Although you can also define a custom service interface using a mapped REST service (that uses the PAS for OpenEdge REST transport) or a user-defined WebHandler, a DOH-based ABL service offers the following advantages over the mapped REST service:

• It supports more content types.
• It is easier to debug, since the DOH is an ABL class. You can also readily inspect and modify its JSON mapping file.
• It is more customizable; you can extend its functionality by accessing its class events. To learn more about these class events, see the white paper on using the DataObjectHandler.
• It uses the WEB transport, which is the recommended way to expose your ABL applications as RESTful services. This is because the WEB transport uses the ABL WebHandler class and thus provides better insight and control over your ABL service.

Overview of steps to use the DOH

1. Create an ABL service — You begin by creating an ABL service that uses the DOH class.
2. Create a mapping file — You then create a mapping file with the same name as the ABL service.
3. Define custom service endpoints — You start describing the service interface in the mapping file by defining your custom endpoints.
4. Associate HTTP verbs with operation handlers — For each service endpoint, you associate an HTTP verb (GET, PUT, POST, etc) with one of the following operation handlers:
   • void, that returns only a status code
   • file, that returns the contents of a file
   • entity, that invokes an ABL class or procedure
5. (Optional) Add mapping metadata for OpenAPI output — Add descriptions, access control, and service-level schemas in the mapping file so generated OpenAPI output is clearer and more complete.

Create an ABL service

The first step is to create an ABL service that uses the DOH. Perform this task as follows:

1. Right-click the root project name in the Project Explorer view in Progress Developer Studio and select New > ABL Service.
2. Select WEB in the Transport drop-down.
3. Enter a name for the service, (such as HelloService).
4. In the WebHandler section, choose Select existing and then browse and select OpenEdge.Web.DataObject.DataObjectHandler.
5. Add a single resource URI that matches the service name (/HelloService).
6. Click Finish.

Create a mapping file

After creating a DOH-based ABL service, you describe its service interface in JSON in a mapping file with the extension .map. The DOH uses this mapping file to execute the service's operations. If a client application attempts to call an endpoint or service that is not described in the mapping file, the DOH returns a 404 (Not Found) error.

Create a new text file in your ABL web app project's /PASOEContent/WEB-INF/openedge folder with the same name as the ABL service and with the extension .map (for example, HelloService.map). The matching filename instructs the DOH to use the mapping file for the service's operations. Placing it in the openedge folder makes it discoverable in the application PROPATH.

At minimum, you need to define a single service within a services object, like this:

{    "services":
      {
        "HelloService": {           
        "version": "1.0.0"       
      }
    }
 }

The service name must match the ABL service and resource URI name that you set while creating the ABL service. The "version" property defines the version of the service and should follow the Semantic Versioning pattern (for example,. "1.0.0"). The JSON snippet, as shown in this example, provides just enough to make the service discoverable but does not do much else. Without this minimum configuration, the server would only return an HTTP-404 response for the service.

Define custom service endpoints

In the JSON mapping file, define custom service endpoints under an operations object. For example:

{
	"services": {
		"HelloService": {
			"version": "1.0.0",
			"operations": {
				"/Greeting": {},
				"/Message": {},
				"/": {}
			}
		}
	}
}

Associate HTTP verbs with operation handlers

For each custom service endpoint, you associate HTTP verbs with operation handlers. You can set up operation handlers for all HTTP verbs that are supported by the WEB transport. In addition to request handling, each verb definition can include metadata such as descriptions, access control roles, and schema details, which improves generated OpenAPI Specification output.

Supported HTTP verbs are:

• GET
• PUT
• POST
• DELETE
• HEAD
• OPTIONS
• TRACE
• PATCH

Specify each verb that you want to use as a JSON object under the service endpoint in the mapping file. For example:

{
	"services": {
		"HelloService": {
			"version": "1.0.0",
			"operations": {
				"/Greeting": {
					"GET": {},
					"PUT": {},
					"POST": {}
				},
				"/Message": {
					"GET": {},
					"PUT": {}
				},
				"/": {
					"GET": {}
				}
			}
		}
	}
}

"/Greeting": {
	"GET": {
		"contentType": "application/json"
	}
}

"/Greeting": {
	"GET": {
		"contentType": "application/json",
		"statusCode": 200
	}
}

"/Greeting": {
	"GET": {
		"contentType": "application/json",
		"entity": {}
	},
	"PUT": {
		"contentType": "application/json",
		"entity": {}
	}
}
"/Message": {
	"GET": {
		"contentType": "application/json",
		"file": "filepath"
	}
}
"/": {
	"GET": {
		"contentType": "application/json",
		"void": null
	}
}

Add mapping metadata for OpenAPI output

Data Object Handler mapping files can include metadata that improves the OpenAPI output generated from your service definitions. In addition to routing and handler selection, you can describe services, operations, and parameters, and provide security and schema information that the OpenAPI writer can use when it builds the specification.

The most useful properties are:

• description: Adds customer-facing text for a service, operation, or parameter. Use it at the service level or within each HTTP verb object. (See the "Description property in mapping metadata" section below for more detail.)
• accessControl: Specifies one or more roles required to invoke an operation. Define it as an array within each HTTP verb object. (See the "Access control in mapping metadata" section below for more detail.)
• schemas: Defines service-level JSON Schema content that can be used to describe request and response bodies in generated OpenAPI output. (See the "Service-level JSON Schema" section below for more detail.)

Example:

{
  "services": {
    "OrderService": {
      "version": "1.0.0",
      "description": "Operations for querying and managing customer orders.",
      "operations": {
        "\/order\/{id}\/status": {
          "GET": {
            "contentType": "application\/json",
            "statusCode": 200,
            "description": "Retrieve the current status of a single order by ID.",
            "accessControl": [
              "ROLE_USER",
              "ROLE_ADMIN"
            ],
            "entity": {
              "name": "MyApp.OrderService",
              "function": "GetOrderStatus",
              "description": "Returns the current status of an order given its ID",
              "arg": [
                {
                  "ablName": "piOrderID",
                  "ablType": "integer",
                  "ioMode": "INPUT",
                  "description": "The numeric ID of the order to retrieve",
                  "msgElem": {
                    "type": "path",
                    "name": "id"
                  }
                },
                {
                  "ablName": "poOrderStatus",
                  "ablType": "CLASS Progress.Json.ObjectModel.JsonObject",
                  "ioMode": "OUTPUT",
                  "description": "JSON object containing the order ID and current status",
                  "msgElem": {
                    "type": "body"
                  }
                }
              ]
            }
          }
        }
      },
      "schemas": {
        "poOrderStatus": {
          "type": "object",
          "description": "An order with its current status",
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique identifier of the order"
            },
            "status": {
              "type": "string",
              "description": "Current status of the order"
            }
          },
          "required": ["id", "status"]
        }
      }
    }
  }
}

OpenEdge.Web.DataObject.Writer.OpenAPI30ServiceWriter

OpenEdge.Web.DataObject.Writer.OpenAPI31ServiceWriter

OpenEdge.Web.DataObject.Writer.OpenAPI32ServiceWriter

After you update the mapping file, regenerate the OpenAPI output and review it to confirm that descriptions, security expectations, and schema details match runtime behavior. For more information, see ABL application catalog service in Manage Progress Application Server (PAS) for OpenEdge.

Description property in mapping metadata

You can add a description string at multiple levels throughout the mapping file. Each description flows into the corresponding location in the generated OpenAPI specification:

Example showing descriptions at service, operation, and parameter levels:

{
    "services": {
        "OrderService": {
            "version": "1.0.0",
            "description": "Operations for querying and managing customer orders.",
            "operations": {
                "/orders/{id}": {
                    "GET": {
                        "description": "Retrieve a single order by ID.",
                        "contentType": "application/json",
                        "statusCode": 200,
                        "entity": {
                            "name": "MyApp.OrderService",
                            "function": "GetOrderById",
                            "description": "Invokes the order lookup handler.",
                            "arg": [
                                {
                                    "ablName": "id",
                                    "ablType": "CHARACTER",
                                    "ioMode": "INPUT",
                                    "msgElem": {
                                        "type": "path",
                                        "name": "id"
                                    },
                                    "description": "The unique identifier of the order to retrieve."
                                }
                            ]
                        }
                    }
                }
            }
        }
    }
}

All description properties are optional and backward compatible. Omitting them has no effect on service operation.

Access control in mapping metadata

The accessControl property specifies one or more security roles required to invoke an operation. Define it as an array of strings within each HTTP verb object:

"GET": {
    "accessControl": ["ROLE_USER", "ROLE_ADMIN"]
}

Role names should match the roles defined in your oeablSecurity.csv configuration file or your Spring Security configuration.

How access control affects OpenAPI output

By default, the OpenAPI writer does not include security information in generated output. To expose access control metadata in your OpenAPI specification, you must programmatically enable it in your OpenAPI service writer configuration. This is an intentional opt-in design. Upgrading to a version that supports this feature does not change existing OpenAPI output behavior.

When security output is enabled:

• If you configure a named security scheme (such as bearerAuth or oauth2), the writer maps accessControl roles to standard OpenAPI security requirement objects under that scheme.
• If no security scheme is configured, the writer outputs roles using an extension property named x-required-roles on each operation.
• Operations whose accessControl roles indicate the requesting user does not have access are omitted from the generated specification entirely. This prevents unauthorized users from discovering endpoints they cannot call.

Service-level JSON Schema

When your service operations accept or return data that is not backed by an ABL Temp-Table or ProDataset, for example, a plain JSON request body or a custom response structure, you can define JSON Schema objects at the service level. The OpenAPI writer uses these definitions to generate components/schemas entries and reference them from the appropriate request or response bodies in the specification.

Defining schemas

You add a schemas object directly inside the service definition. Each named entry follows the standard JSON Schema format:

{
    "services": {
        "OrderService": {
            "version": "1.0.0",
            "schemas": {
                "OrderRequest": {
                    "type": "object",
                    "description": "Payload for creating or updating an order.",
                    "properties": {
                        "customerId": {
                            "type": "string",
                            "description": "The customer placing the order."
                        },
                        "items": {
                            "type": "array",
                            "description": "Line items in the order.",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "sku": { "type": "string" },
                                    "quantity": { "type": "integer" }
                                }
                            }
                        }
                    }
                },
                "OrderResponse": {
                    "type": "object",
                    "properties": {
                        "orderId": { "type": "string" },
                        "status": { "type": "string" }
                    }
                }
            }
        }
    }
}

Schema definitions can be nested to any depth. You can add a description to the schema itself and to individual properties. Both flow into the generated OpenAPI output.

Referencing schemas from operations

To associate a schema with a request or response body, set the ablName of the body parameter to match the schema name you defined:

"/orders": {
    "POST": {
        "contentType": "application/json",
        "statusCode": 201,
        "description": "Create a new order.",
        "entity": {
            "name": "MyApp.OrderService",
            "function": "CreateOrder",
            "arg": [
                {
                    "ablName": "OrderRequest",
                    "ablType": "CLASS Progress.Json.ObjectModel.JsonObject",
                    "ioMode": "INPUT",
                    "msgElem": { "type": "body" }
                },
                {
                    "ablName": "OrderResponse",
                    "ablType": "CLASS Progress.Json.ObjectModel.JsonObject",
                    "ioMode": "OUTPUT",
                    "msgElem": { "type": "body" }
                }
            ]
        }
    }
}

The OpenAPI writer matches the ablName of each argument with a field or body message element against the service-level schemas entries. When a match is found, the generated specification uses a $ref to the corresponding schema definition rather than an untyped object.

How JSON Schema coexists with ABL schema types

The DOH supports three types of schema definitions in mapping files:

The DOH inspects the structure of each schema entry to determine its type. If a definition does not match the expected format for a dataset or temp-table, it falls through to be treated as a JSON Schema and is passed through to the OpenAPI writer as-is.