Here is a detailed description of how you can use each of the DOH's operation handlers.

void

The void operation handler returns only the status code that is defined for the HTTP verb. This is useful in certain situations. For example, when you want to reserve an endpoint for future enhancements (via a 501 - Not Implemented status code) or when you want to use it to confirm that the server is alive (204 - No Content).

Use the void handler as shown in this example:

"/CustomizedGreeting": {
	"GET": {
		"contentType": "application/json",
		"statusCode": 501,
		"void": null
	}
}

file

The file operation handler returns the contents of a file, as long as the contents of the file conform to a supported MIME type.
Note: For the file operation handler to work, the file must be placed within the web app directory, but not in the WEB-INF folder for security reasons. The static folder is the recommended location for it.
Since the web app may be deployed to different PAS for OpenEdge instances, as the ABL code gets moved from one environment to another (for example, from development to testing or from testing to production), the best practice is to reference the PAS for OpenEdge and web app directories using environment variables:
Directory Environment variable
PAS for OpenEdge instance root ${env.CATALINA_BASE}
Web app directory (located in webapps in the PAS for OpenEdge instance root directory) ${web.webapp}

For example:

"/Message": {
	"GET": {
		"contentType": "application/json",
		"statusCode": 200,
		"file": "${env.CATALINA_BASE}/webapps/${web.webapp}/static/message.json"
	}
}

entity

You use the entity operation handler to map an HTTP verb with an ABL procedure or an ABL class method. At runtime, when the verb is used in an HTTP request to the service endpoint, the associated ABL procedure or class method gets executed.
Note: Although this operation handler is called entity, its use is not limited to ABL Business Entities. You can use it to reference any ABL class or procedure.

Here is a simple example of the entity handler:

"/Greeting": {
	"GET": {
		"entity": {
			"name": "Customer.Greeting",
			"function": "getPersonalizedGreeting",
			"arg": [
				{
					"ablName": "Cust-Name",
					"ablType": "CHARACTER",
					"ioMode": "INPUT",
					"msgElem": {
						"type": "query",
						"name": "CustomerName"
					}
				},
				{
					"ablName": "GreetingMessage",
					"ablType": "CHARACTER",
					"ioMode": "OUTPUT",
					"msgElem": {
						"type": "field",
						"name": "Message"
					}
				}
			]
		}
	}
}

The name property identifies the ABL class (Customer.Greeting) that is to be referenced; the function property denotes the method (getPersonalizedGreeting) in the class that needs to be invoked. The ioMode property identifies the parameter type (INPUT, OUTPUT, etc).

The arg property (short for arguments) is an array of JSON objects. Each object maps to an input or output parameter that is required by the getPersonalizedGreeting method. The first three properties in each arg object (ablName, ablType, and ioMode) identify the ABL parameter and correspond to how the parameters are defined in the ABL method:

METHOD getPersonalizedGreeting(INPUT Cust-Name AS CHARACTER, OUTPUT 
GreetingMessage AS CHARACTER):
...
END.
The last property in each arg object--msgElem--defines how the parameter maps to a message element in the HTTP request or response. Parameters of the type INPUT retrieve their values from message elements in HTTP requests. Parameters of the type OUTPUT pass on their values (returned by the ABL method or procedure) to message elements in HTTP responses. The msgElem object therefore consists of two properties:
  • The type of message element in an HTTP request or response. Examples include query, header, etc.
  • The name of the message element in an HTTP request or response. Examples include customer-id (for a query), From, Host (for a header), etc.

At runtime, the DOH uses these property mappings to convert HTTP requests and responses into ABL objects. In some cases, such as for parameters that are of the type INPUT-OUTPUT, you may need to map HTTP requests as well as HTTP responses to the same parameter. In this case, you can use msgElem as an array as shown here:

"arg": [
	{
		"ablName": "CustomizedMessage",
		"ablType": "CHARACTER",
		"ioMode": "INPUT-OUTPUT",
		"msgElem": [
			{
				"type": "query",
				"name": "customer-name" 
			},
			{
				"type": "field",
				"name": "message"
			}
		]
	}
]

These examples illustrate a couple of different ways in which you can use the entity operation handler. The complete list of entity handler properties and the types of values that you can set for each property is described in the Entity Handler properties section.