Configuring the REST Resources

This topic explains how to configure REST services using the EJB-REST wizard. You can use the EJB-REST wizard to expose EJB methods as REST services. For RESTification, an EJB method must follow certain guidelines. For more information about these guidelines, see the Guidelines for RESTification of EJB Methods topic.

Creating a REST Resource

You can create a new REST Resource by accessing the Eclipse EJB-REST Wizard in one of three ways:

Select Junos Space > Manage REST Services from the Eclipse menu bar.
Click the Manage REST Services button on the Eclipse toolbar.
Select the EJB Java interface file in the Eclipse project explorer tab, right-click, then select the Create/Edit REST Services option.

The Manage REST Services screen is displayed (only in cases 1 and 2):

The Manage REST Services screen displays all the REST Services currently RESTified. To create a new REST service or interface, click the button.

The REST Interface Creation screen will open.

Here you can select the EJB Source Interface and the EJB Source Implementation files, the Interface Target Context, and the Interface Target File.

If you use the Browse button to select the EJB Source Interface, the dialog will automatically find the first implementation which uses that interface. If there is more than one implementation, you can choose a different implementation by clicking on the Browse button next to EJB Source Implementation. Similarly, you can choose EJB Source Implementation first, and the dialog will automatically find the EJB Source Interface that the implementation uses.

The Manage REST Services screen is displayed (only in cases 1 and 2).

The Manage REST Services screen displays all the REST Services currently RESTified. To create a new REST Service/Interface, click the button.

The REST Interface Creation screen opens.

Here you can select the EJB Source Interface and the EJB Source Implementation files, the Interface Target Context, and the Interface Target File.

NOTES:

The Java package is automatically filled in when this screen is accessed using method 3 above (REST Interface selection).
The Java package selected for the Interface Target Package might not already exist, but the Web Service Project must have already been created in Eclipse, using the SDK Project Creation Wizard.
Interface Target Context is the Context Root from the application.xml file. The Context Root is always associated with a single Web Service Project. You can change this field to point to another Context Root for a different Web Service, but you can only change it once, during the initial REST interface creation. Also, note that, once you set the Interface Target Context, all new Web service Java files and schemas will be created in the Web service project that exposes that Context Root in application.xml file.
To accept the entries on this screen, click Next. The second REST Interface Creation screen is displayed.

Configuring REST Resource

To expose an EJB interface method through the REST interface and configure REST methods, use the following steps:

The following fields are displayed in the second REST Interface Creation screen:

Resource Path:

Context Root—This is the context root from application.xml (see the last Note in the previous section for an explanation).
Service Root—This is the URI path component that distinguishes this service from other services defined in the same Web Service Project. Most of the time, you will only have a single Web service per Web Service Project, so you can set the Service Root to just "/". The Service Root field can be changed at any time during or after the initial wizard RESTification.

Methods of EJB Interface—Lists the EJB methods that are available in the EJB interface file.

Methods of REST Interface—Lists the methods already exposed through the REST interface. Initially this table is empty, indicating that no method is exposed through the RESTful service.

Select a method from the Methods of EJB Interface table, and click +REST (the +REST icon). In this example, the getAllCountries method is selected. The Configure REST Method window for the selected method is displayed:

You can edit the fields in the Configure REST Method window as follows:

HTTP Method drop-down—Selects the HTTP method (GET, PUT, POST, or DELETE).

@GET if the EJB method name starts with get or any other name
@PUT if the EJB method name starts with update, modify, edit, or set
@POST if the EJB method name starts with add, create, exec, run, or process
@DELETE if EJB the method name starts with delete, remove, or del

Sorting / Filtering / Paging check box—If this box is selected, a new parameter class, UriContext (with the annotation @Context) is added to the Parameters table. The UriContext parameter facilitates passing Sorting, Filtering, and Paging parameters to the REST Method, transparently. This checkbox is only available for collections.
Method Path—Lists the URL path, which is the path of the URL for the method being RESTified. The URL path is composed of the context root followed by the service root and, in the text field, the method name and parameter list.

Note: The URL path is composed of: context root + service root + method name + parameters.

Parameter properties can be edited in the parameters table, using in-place editors. Click on a value to activate the editor. The Method editor has two parameter tables: a general parameters table and a body parameters table. Switching the parameter category can move a parameters between the tables:

The Following table columns can be edited:
- Parameter Annotation drop-down—Lists the parameter annotations.
- Path param— Path Parameters are parameters that are passed into the API as segments of the URL. For example, in the URL /api/jssdk/hello-world/world/countries/{id}, {id} is a path parameter designating the ID of a given country in the countries primary collection. Selecting Path Pram will direct the wizard to generate the @PathParam in the Java code for the REST method parameter.
- Query Param— Query parameters are parameters that are passed into the API after the URL part of the API. These parameters are always preceded with a "?" character. Selecting Query Param will direct the wizard to generate the @QueryParam in the Java code for the REST method parameter.
- HTTP Request Body— HTTP Request Body parameters are passed into the API through the HTTP Body or payload of the HTTP Request. Selection of this field creates the REST DTO as the envelope.
- None—This indicates that the EJB parameter is not going to be passed into the REST method. When the EJB method is called, a default value corresponding to that parameter class is passed in (null for String and complex types, 0 for int, and true for boolean).
- Parameter Name—This is the REST Parameter Name which is, initially, set to the name of the EJB method parameter. You can change the REST Parameter Name to be different from the EJB parameter name. Normally, you would not want to change the name of the REST parameter.
- Is this parameter required?—Displays only for @QueryParam parameters. By default, the check box is selected. If you specify the parameter is to be required, the code generated contains a @Required attribute. This property can later be retrieved using the /api/info service. For more information, see the Rest Annotation topic.
- Up and down buttons change parameters order.
- Clicking Edit for simple type parameters will display the following dialog:

Clicking the Edit button for complex type parameters opens the DTO editing wizard.

The Method editor wizard allows editing Media Type identifiers and supported Representation Formats. The Media Type is a unique type which identifies the DTO object, configured in either the Request or Response Message Body of the Method Edit dialog.

The RBAC capabilities editor is available in the respective accordion tab.

Configuring RBAC

RBAC Method Properties accordion tab allows you to configure the role-based access control (RBAC) capability for the method you are exposing through the RESTful service.

You can edit the fields in the Configure RBAC window as follows:

RBAC On/Off—Allows you to add a role-based capability to your method. By default, it is selected. If you clear it, the RBAC Type and RBAC Capability fields are disabled. Also the @RBAC annotation is removed from the Method Signature Preview field.
RBAC Type—Allows you to select the RBAC type such as CREATE, READ, UPDATE, or DELETE.
RBAC Capability—Allows you to select the RBAC capability from the Capability table. Capabilities are defined in the Module.xml Editor. The REST Wizard creates an @RBAC annotation using the RBAC Type and an RBAC Capability. When the method is called by the client, RBAC checking is done to authorize the call by comparing the user's role capabilities to the capabilities specified in the @RBAC annotation.
Object/Reference
- Object—Allows you configure REST DTO as an object. This means that you will be defining all fields associated with the object. The Wizard will provide a proposal for this check box, which is usually correct.
- Reference—It allows you to configure the REST DTO as a reference to an object. An example of this would be a list of roles for a user. The roles that are part of the user are not the actual roles, but are references to roles that exist in the Primary Roles Collection (more on this in subsequent sections). For a discussion on how to configure the REST DTO as a reference, see Configure DTO as a Reference
Method Signature Preview—Displays the method signature.

When finished on the Configure RBAC screen, click Next to display the Configure REST DTO screen.

Configuring Optimistic Lock Retry

When configuring a method that could potentially update a database table using Optimistic Locking (PUT, POST or DELETE methods only), you can configure an Optimistic Lock Retry and Yield Time, using the two sliders on the Configure REST DTO screen:

The Retry Count represents the number of times the EJB method will be called if the method fails with an OptimisticLockException. After this number of retry calls, if the EJB method throws another OptimisticLockException, the server will return with HTTP error code 428 (Precondition Required). If the EJB method throws any exception other than OptimisticLockException, the REST method will progress normally, meaning that it will not retry the operation but forward the exception to the appropriate exception mapper.

The Yield Time value represents the amount of time (in milliseconds) that the REST method waits before retrying another call to the EJB method.

By default, the Retry? checkbox is always selected for all PUT, POST, and DELETE methods. the Retry Count is set to 3 and the Yield Time is set to 100 ms. For PATCH HTTP methods, the Retry Count and Yield Time are equal to the value set for the corresponding PUT, POST, and DELETE methods that the PATCH method calls internally.

Configuring REST DTOs

REST DTOs are Java Beans that are serialized into an XML or JSON HTTP request or a response. After you configure your XML request or response data for your REST Web services, the Wizard creates a top-level DTO. When the generated REST services is subsequently invoked, the DTOs are serialized into the actual XML or JSON data.

You can configure a top-level DTO, by clicking on one of the Edit buttons to the right of either the Request or Response Message Body. The resulting dialog is the Configure REST DTO screen (shown below).

Note that the dialog name that appears in the dialog header will depend on which type of DTO object being configured, which is either a collection or a member of a collection.

The DTO Edit dialog displays a table, listing simple and complex fields from the EJB Model object. In this example, countries is a complex property. You can select the fields that you want to include in the REST DTO from the list.

Note: Each Top-level DTO has an unique media type that was configured in the Method Edit dialog in the previous section. This means that the same DTO can be used for GET, PUT, and POST methods (if they share the same media type). For example, a "GET /api/jssdk/countries/3" response DTO is the same as the "POST /api/jssdk/countries" request DTO. In both cases, it is the DTO associated with the media type: application/vnd.jssdk.hello-world.world.country. Therefore, when configuring the DTO for the PUT, POST, or GET method, you must select all the fields required for a GET. Deselecting a field while configuring the REST DTO in the PUT or POST method will also deselect it for the corresponding GET method as well as the PUT or POST response. If you want to exclude the field from the POST or PUT HTTP Request Body, but still want to include it in the GET response, you should configure the field as "non-required" by deselecting the "Required" check box. Go to the Make Field Non-required discussion below.

The XML Preview is displayed for the selected DTO fields in DTO Preview accordion tab:

The XML displayed in this tab depends on the following scenarios.

Scenario 1: An EJB Object is an interface or an abstract class.

Note: You must define a valid setter and getter for a given field before configuring it. The rules for a valid setter or getter are:

The name of a getter method must start with "get" and a setter with "set."
A getter method must not have any parameters. For example, public int getId(int i) is an invalid getter.
A setter method must have one parameter, whose type must be the same as the return type of the corresponding getter method. For example, public int getId() and public void setId(int id) is a valid getter/setter pair.
The return type of a setter method must be void. For example, public int setId(int id) is an invalid setter.
The getter and setter methods should have the public access specifier.

Scenario 2: An EJB Object has a reference to an interface or an abstract class:

The wizard will consider the field as a complex type, and it will get all the fields based on the valid getter/setter available in that complex type. Fields that do not have valid getter or setter methods are displayed in RED.

Scenario 3: When an EJB object is a concrete class, but also extends any abstract class or implements any interface (except marker interfaces), or contains a reference to any one of these in the EJB Object:

The fields in the wizard are displayed, based on the valid getters/setters from the interface, abstract class, and concrete class.
Any fields that do not have valid getter or setter methods are highlighted in RED.

Scenario 4: When an EJB Object interface extends other interfaces, or an EJB Object class extends other abstract classes that further implement interfaces:

The fields in the wizard are identified based on a valid getter/setter and are shown in the wizard for all levels.
Any fields that do not have valid getter or setter methods are highlighted in RED.

Configuring HATEOAS Methods

The Configure REST DTO window allows you to enter details for the HATEOAS methods. For more information about HATEOAS, see the Overview of HATEOAS topic. To configure the HATEOAS method, follow these steps:

Edit the fields in the Configure Method window as follows:

Element Name—Allows you to enter the name of the element.
Description—Lists the EJB methods that are available.
HREF drop-down—Lists the methods exposed through the REST interface. Initially the list is empty, except if a method with complex parameters is added as a POST HTTP method. In that case, its HREF values are displayed.
HATEOAS Method Preview—Displays a preview of the XML and the code that will be generated.

Click OK or Cancel to return to the Configure REST DTO window.

Editing DTO fields

Continue the DTO editing by selecting a complex property (country, in this example) and clicking Edit to modify the complex property in the REST DTO. The Member of Collection window is displayed.

You can edit the fields in the Member of Collection screen as follows:

Sortable—If this check box is selected, the @Sortable annotation is added to the getter method of this field. An app-info tag is also generated in the schema.

Filterable—If this check box is selected, the @Filterable annotation is added to the getter method of this field. An app-info tag is also generated in the schema.

Href—Any DTO can be either Object or Reference. Reference is a DTO that has an href attribute pointing to the same logical object in its primary collection (a URL that actually manages the object's life cycle). Object assumes there is either no primary collection for the DTO, or the current method is a part of the primary collection. The href value is pre-populated with the method name followed by the path parameters and key because the wizard automatically assumes that the primary collection exists based on the path.

URI—If the current DTO is mapped to an URI, the URI value can be edited. The REST Wizard also tries to guess the value by examining existing methods. This URI is a URI of the method, that returns the current DTO. The URI consists of two parts: the one set for this DTO parent (not editable), and the part related to the DTO itself (can be edited).

DTO Preview—This section displays the XML preview for the property.

Select the pull-through fields displayed and click Edit. The Configure Property window for the selected property is displayed.
Note: You can use the Up and Down buttons to change the order of DTO and pull-through fields. Selected fields are used to form the schema. The fields without a proper getter or setter cannot be moved up or down and the option is disabled for invalid fields.

You can edit the fields in the Configure Property screen as follows:

XML Annotation—Enter the value for the XML element annotation.

Wrap the field's value in CDATA—If this check box is selected, the DTO field is marked as the CDATA field. The generated DTO contains a @CDATA annotation for the corresponding field.

Note: This field is displayed in the case of a secondary collection only.

Click OK to return to the Member of Collection screen that displays configured properties.
Click Finish two times to return to the method editor.

Configuring Media Type

Media Type and Format combo boxes are used to modify method media types for both Request and Response Message Bodies:

The following are available representation formats:

XML—Select to have this REST API accept or return XML-formatted input/output represented by the media type.
JSON—Select to have this REST API accept or return JSON-formatted input/output represented by the media type.
Both—Selected by default. Configures this REST API to accept or return both JSON-formatted and XML-formatted input/output represented by the media type.

Note: When configuring POST or PUT methods, the dialog will automatically set the Response Message Body format to be the same as the format the user selects for the Request Message Body. For a PATCH method, only XML format is supported for the Request Message Body, but the user can still select all three formats for the Response Message Body (for a single object PATCH only).

Click Finish to return to the resource editing wizard.
Click Finish. The first version (v1) of the REST interface, the REST Implementation class, DTO classes, and DTO schemas are generated:

Configure a DTO as a Reference

To configure a DTO as a reference, select "Reference" instead of "Object" on the Configure DTO screen.

For example, this would be the case if you were configuring a method such as addStateToCountry() and you were going to specify that a reference is used to add the state, instead of the actual state itself. Similarly, you would pick "Reference" if you were configuring the method getCountry(countryId), and you were configuring the member state of the country.

Notice that the DTO field table is disabled. This is because you are configuring a POST method for adding a state reference to a country, and the POST method does not need to have any of the state fields specified because this is just a reference to a state that already exists in the primary states collection.

However, when we configure the same state_REF DTO, but for a different method getStateForCountry(int countryId, int stateId) the same fields table is not disabled. In this case, this is because even though the state returned is a reference, you might still want to configure some pull-through fields for it. (See the XML preview below.)

When configuring the media type on the last screen, note that the media type name proposal given by the wizard in the case of both addStateToCountry() and getStateForCountry() ends with state-ref and not state. This is significant because the DTOs for state and state-ref are different in that they could potentially have a different set of fields. By default, the dialog always selects only the id and name fields for the reference DTO, except for all the fields with valid getter and setter methods for the object DTO.

Configuring Reference Templates (Using Dot Notation)

In the previous section, we configured a simple template for the HREF field:

/api/jssdk/hello-world/hello-world/states/{id}.

Actually, this template was already pre-configured for you by the wizard when it recognized that the DTO was a reference and a secondary collection member and set the HREF to point to the corresponding member of the primary collection of states. The wizard was also able to recognize the "id" field in the DTO as a key field for states and set the template variable to {id}.

Note: "id" is actually the name of the Java field, not the corresponding XML name. In this case, they happen to be the same, but you may want to have a more complicated name for the key, so you need to remember to use the Java name, not the XML name.

Sometimes the wizard may not be able to select the correct template and will need some help from you. This happens when the DTO does not have a field called "id" or does not have the "id" as part of the field name. Also, there could be many fields with "id" in the name, and the wizard may not know which one to pick as the key. You may also want to use "name" (although, that is not recommended) or some other field as the key field. In all of these instances, you need to specify your own key field.

As you fill in the key field's name in the template, you will notice that the wizard automatically selects that field in the DTO, if it was not already selected prior to you filling in the field's name. This is necessary because the field needs to be present in both the input and the output of REST methods. When the template is used as an output body, the REST infrastructure code on the server will fill in the template with the value of the key field and generate the correct HREF value. On input, if the HREF is specified by the user as an attribute of a reference, the HREF will be parsed according to the template, and the field's value will be filled in by the REST infrastructure code.

In this example, you specified the "id" field of the current DTO. However, the key field may not be part of the current DTO at all. The key field can be contained in a child or a contained DTO. In that case, the wizard will allow you to specify the key field in the template, using the Dot Notation. For example you can specify:

/api/jssdk/hello-world/hello-world/states/{stateInfo.stateId}

This would be the case if the ID was actually not part of the current State object, but contained inside the stateInfo object's stateId field. Notice that for both variables, the actual Java object names are used, not the Java class names.

Let's say we had a link called country which we wanted to use inside a state object. Note the hierarchy of the current State DTO:

/api/jssdk/hello-world/hello-world/country/states/state

In this case, we can use the Dot Notation to specify the key as follows:

/api/jssdk/hello-world/hello-world/country/{_parent._parent.id}

The first "_parent" would take us back to the states level, the second "_parent" would take us to the country level, and we will find the country ID there. Notice how the Dot Notation is a path specification for the current DTO hierarchy and not for the actual template hierarchy.

The Dot Notation can be used anywhere where you can specify a template, such as in URIs, HREFs, and method links.

Configure a Heterogeneous DTO as a Reference

The Heterogenous secondary collection is a collection of DTOs or objects, where each member DTO is a reference to a primary collection object. For example, if in the HelloWorld application, State class has two descendant classes: EvenState and OddState, and there are two primary collections (one for EvenState and another for OddState), then any secondary collection of State might be treated as heterogeneous.

The REST Wizard detects potential heterogeneous secondary collections automatically when a base class is used for a Model Object. In such a case, an "Heterogeneous?" check box appears on the secondary collection DTO page in the Object/Reference section.

If the "Heterogeneous?" check box is disabled, the secondary collection of State will be treated as a regular (homogeneous) collection. Enabling the check box makes the Href textbox disabled. In this case, the "Edit Hrefs" button appears, allowing the user to edit multiple href values, one for each descendant class:

As a result, each State inside Country has the href value generated based on its actual class: EvenState or OddState:

Only base class (superclass) properties are supported as pull-through fields. Any additional properties, which are declared in descendant classes, are ignored. So for the EvenState/OddState example, only base State class properties (id and name) are included in the response XML.

Note that the base class source code does not need to be part of the application. It can be derived using a Java class file that is placed in a shared jar file. This way multiple apps can share a base class that is exposed by a single app or the platform.

If the DTO is a single class DTO with no base class, you can still enable a heterogeneous configuration by selecting the "Heterogeneous?" checkbox. In this case, the wizard cannot find the href templates for the heterogeneous collection, and the application code needs to supply the href and type values at run time. This can be done by creating two additional fields in the EJB Model Object: link and type. These fields are XML Transient and are annotated with the @XmlAttribute annotation.

@Transient
@XmlAttribute(name = "href", required = false)
protected String link;
	
@Transient
@XmlAttribute(name = "type", required = false)
protected String type;

In addition, when the MO object is accessed with a REST call, it is the responsibility of the EJB to set these two fields with their corresponding href and type values. In this way, this mechanism allows each app to set these attributes dynamically. Note that these fields do not need to be persisted in the database or be part of any entity object. They are there to return href and type values back to the REST method. The wizard generated code will get these values and set the corresponding attributes in the response.

Also note that a heterogeneous link does not need to be part of a collection. You can have a single reference anywhere in your XML or JSON body, and it can be either a homogeneous or a heterogeneous reference. The wizard will allow you to configure a heterogeneous reference every time you check the "Reference" checkbox.

Shared DTOs

Top-level DTO can be shared for method request and response as well as between several methods (for example, in CRUD methods). A shared DTO means that the same DTO Java class is used as parameters in different methods, so any changes to the DTO in one method affects it in another method.

For example, in the addCountry() method in the HelloWorld example, the request and return Country DTO is shared, and the changing request Country DTO will also affect it for the response. The Country DTOs for CRUD methods getCountry(), addCountry(), and updateCountry() are also shared.

The base rule for DTO sharing is simple: if two DTOs have the same media type by default (on initial EJB RESTification), those DTOs are shared. Note that this means that if you change the media type name from its default name, this will not force the Wizard to create a new DTO Java bean. It will only change the media type designation of the DTO, but the DTO will still be shared with other DTOs in the other CRUD methods.

While being effectively the same Java class, shared DTOs behave a bit differently for request and response. The request DTO editor has an additional column for the Required DTO property:

All properties checked in the left column will be included in a Java class, and thus transferred to or from the client on a REST method envocation. But non-required properties can be omitted when transferring the object from the client to the server with a POST or PUT request. In the example above, the id property of Country< will be returned by the GET request on a country, but the user can omit the id property when PUTing or POSTing a country.

Single-Getter and Relative DTOs

A single-getter DTO is a DTO that is returned by a GET method, which fetches a single object (for example, GET /countries/12345). Every single-getter DTO is a top-level DTO. When a single-getter DTO is configured in the Wizard, and the configuration is saved, some of the properties of this DTO are copied to its relative DTOs. Relative DTOs are DTOs that are built from the same source EJB Modeled Object. Both collection and reference DTOs are relative DTOs. For example, the DTOs States.State, Country.States.State, and State_REF are all relatives of the State DTO.

The properties that are copied from the single-getter DTO to the relative DTOs are:

Required
Read Only
Range (for integers)
Default
CDATA (for strings)
Documentation (all properties)
Selected properties—Properties that are not selected in the single-getter DTO will not be select in the relative DTOs, but the user can deselect some of the properties in the relative DTO.

Note that although the user can override these properties in the relative DTO, there is no reason to do that because these properties would just be overwritten again when the single-getter DTO is modified.

Therefore, it is highly recommended that the only configurations that the user should change on the relative DTOs are:

Deselection of properties configured for the single-getter DTO.
Up-down ordering of properties.
HREF and heterogeneous link selection.
Sortable and filterable.
Pull-through links selection.

In fact, the wizard will not allow the user to modify most of these single-getter DTO properties in relative DTOs.

All the other DTO properties should be configured in the single-getter DTO only.

Configuring the REST Services