Try OpenEdge Now
skip to main content
Configuration
Configuring third-party Web applications : OpenEdge Management REST API framework : Parameter annotations
 

Parameter annotations

Several parameter annotations are available that perform type conversion, resource lookup, URL parameter mapping, and query parameter mapping from the HTTP request. The FathomAPIServletHandler has methods to access the URL, query parameters, HTTP requests and response objects.
You can define any number of parameters for a method. If any parameter cannot be resolved based on its annotation, the parameter value is set to null for Object parameters and default value for Java scalar types (int, float).
A few annotations are provided for your convenience; using them is not mandatory:
QueryParam
Add this to a method parameter to retrieve a value from the query to the URL.
For example:
@RequestMapping(path = "/get", method = RequestMethod.GET)
public Object getSample(@QueryParam("id") String idFromQuery) {
    ...
}
PathParam
Add this to a method parameter to retrieve a value from a parameterized URL.
For example:
@RequestMapping(path = "/get/{id}", method = RequestMethod.GET)
public Object getSample(@PathParam("id") String id) {
    ...
}
RequestPathParam
Add this to a method parameter to assign the parameter to a source object based on a fully qualified resource key. The value of the key is derived from a URL parameter.
If the resource defined from the value of the key does not exist, the method is not called and a 404 Resource Not Found response is returned to the caller. If the resource exists, but cannot be cast to the data type defined by the method parameter, the caller receives a 403 Bad Request with a JSON response body. The error response indicates that incorrect resource type was discovered by the resource key in the URL.
For example:
@RequestMapping(path = "/get/{key}", method = RequestMethod.GET)
    public Object getResource(@ResourcePathParam("key") IResource resource) {
        ...
    }
Files
Handles an HTTP multi-form encoded request that contains files. The files are saved to disk and passed as a list of UploadedFile objects with details from the POST method.
For example:
@RequestMapping(path = "/files", method=RequestMethod.POST)
public Object postFiles(@Files List<UploadedFile> files) {
}
Body
Maps the body of the resource to the method parameter. The framework assigns the value based on the data type of the parameter. This is only for use with PUT, POST, and DELETE methods. HTTP requests that user GET method do not have body content.
Note: To ensure that the string conversion behaves properly, the client must send the character set information with the Content-Type header when posting the data using the POST method. If the charset field of the Content-Type header is not available, OpenEdge Management assumes that the character set is IS8859-1. If the Content-Type is specified as application/JSON, the header must be UTF-8.
An example with String as the data type is provided in Table 6:
Table 126. String REST API method
@RequestMapping(path = "/content", method=RequestMethod.POST)
public Object postFiles(@Body String requestBody) {
}
OpenEdge Management uses the Jackson JSON parser. If the request Content-Type is specified as application/JSON, OpenEdge Management attempts to read the request content and convert it to a Jackson ObjectNode implementation.
An example with Jackson ObjectNode as the data type in Table 7:
Table 127. Jackson ObjectNode REST API method
@RequestMapping(path = "/post/{id}", method = RequestMethod.POST)
public Object postSample(@PathParam("id") String id, @Body ObjectNode body) {
}
Jackson can convert a JSON structure parsed from a string to a Plain Old Java Object based on standard getter/setter and few annotations. It also supports some annotations on the entity class methods to determine how deserialization is to be performed. The OpenEdge Management REST API framework built this ability to REST handler methods via annotations.
The following example defines a class MyThing and uses Body annotation to import a request body from the POST method to a MyThing object. Jackson maps properties from the JSON request body.
Table 128. Sample JSON POST content
{
    "id" : "someid",
    "description" : "some description"
}
Table 129. MyThing.class and REST API method
@RequestMapping(path = "/post/{id}", method = RequestMethod.POST)
public Object postThing(@PathParam("id") String id, @Body MyThing thing) {
 
}
 
public class MyThing {
    private String id;
    private String description:
 
    public String getId() {
        return id;
    }
 
    public String getDescription() {
        return description;
    }
 
    public void setId(String id) {
        this.id = id;
    }
 
    public void setDescription(String description) {
        this.description = description;
    }
}