Annotations are like meta-tags that you can add to the code and apply to package declarations, type declarations, constructors, methods, fields, parameters, and variables. They provide helpful ways to indicate whether the methods are dependent on other methods, whether they are incomplete, whether the classes have references to other classes, and so on.
The Junos Space SDK REST Web services are based on the third-party framework RESTEasy. RESTEasy is an implementation of the JAX-RS specification JSR 311. This section briefly describes RESTEasy and provides a high-level introduction to developing REST Web services using RESTEasy, along with an introduction to annotations that are used to develop a Web service.
For more information about RESTEasy, see the following:
Collectively, the supporting tools and techniques an SDK developer uses to build a REST Web service with Junos Space are:
Some of the common annotations used to develop a Web service are described in the following sections.
The @Path annotation is used to specify the URI through which a resource and an API can be accessed. Resource in this case is the REST Web service itself. Thus this annotation is present at the class level as well as the method level. It is mandatory to annotate a REST Web resource class with the @Path annotation. Thus if a user wants to access the 'Countries' through the resource 'WorldCities' context, then:
As a best practice, the class-level path annotation should be a noun that qualifies the Web service, and the method-level annotation can be a noun or an action (for example, user and add-user, respectively).
The following example shows the usage of the @Get annotation and how the method marked with this annotation can be invoked by a REST client.
@Path("countries") // (1)
@GET // (2)
@Produces("application/vnd.jssdk.world-cities.countries+xml;version=1") //(3)
public Countries getCountries();
HTTP/1.1 GET: /api/jssdk/world-cities/countries // (4)
Host: <host-name>:<port>
Authorization: Basic c3VwZXI6anVuaXBlcjEyMw==
Accept: application/vnd.jssdk.world-cities.countries+xml;version=1// (5)
There are two media type annotations: @Consumes and @Produces.
The @Consumes() annotation specifies the list of media types consumed by a particular API or class. This annotation is optional at both the class and API levels. If it is present at both levels, the method-level annotation takes precedence. If the annotation is not present at any level, by default the "text/html" media type is returned.
Examples:
The @Produces annotation specifies the list of the media types produced by a particular API or class. This annotation is optional at both the class and API levels. If it is present at both levels, the method level annotation takes precedence. If the annotation is not present at any level, by default the "text/html" Media Type is returned.
Examples:
Note: Media types specify data representation formats. The data objects consumed and produced by the services are automatically marshalled and unmarshalled into the specific representation by RESTEasy.
Below is a list of Junos Space SDK annotations that can be used on REST resources.
ANNOTATION | EXAMPLE | DESCRIPTION |
---|---|---|
@Filterable | @Filterable(moAttrName = "country") public String getName() { return name; } |
Applicable on the getter/setter of REST DTOs. This
annotation enables filtering on the REST level. It
provides the name of the attribute in the EJB
managed object class that is mapped to the attribute name
in the REST DTO, which will be used in creating filtering
query criteria. Variables: moAttrName: Name of attribute in the EJB managed object class |
@HATEOAS | @XmlElement(name= "states") @HATEOAS(uri = "/states" ,context = HATEOAS.LinkTypeEnum.URI) private States states = null; |
Applicable on the fields or getter/setter of any field
REST DTO. This annotation adds HATEOAS links on the
returned XML or JSON of the REST API. Variables: uri: This is used to create the URI of the HATEOAS link. The URI is always built from the URL being accessed. href: This is used to create the href of the HATEOAS link. The complete href link is created using the value of the context field of this annotation. context: For more information about HATEOAS, see the Junos Space SDK Application Developer Guide. |
@HATEOASMethod | @XmlElement(name= "method") @HATEOASMethod(href = "/states" ,description="To add states") private HATEOASMethodObject addState = null; |
Applicable on fields or getter/setter of any field REST
DTO. This annotation adds HATEOAS links for POST methods
on the returned XML or JSON of the REST API. Variables: description: This value is shown as the link type in the HATEOS method. href: This is used to create the href of the HATEOAS method . The complete href link is created using the value of the context field of this annotation. context: For more information about HATEOAS, see the Junos Space SDK Application Developer Guide. |
@Sortable | @Sortable(moAttrName = "name") public String getCountryName() { return name; } |
Applicable on getter/setter of the REST DTOs. This
annotation enables sorting on the REST level. It provides
the name of the attribute in the EJB managed object class
that is mapped to the attribute name in the REST
DTO, which will be used in the creating the sorting
query criteria. Variables: moAttrName: Name of the attribute in the EJB managed object class. |
@RBAC | @GET @RBAC(type = { CRUDEnum.READ }, capability = { "WorldCitiesCap" }) public Country getCountryById(@PathParam("id") int countryid) |
Applicable on methods of EJB or REST. This annotation
is used for role-based authentication. If you want a user
with some specific capabilities to only access your REST
API, you need to annotate your REST method with this
annotation. Variables: Type: Type of CRUD operation that the CREATE, READ, UPDATE, DELETE, and ALL API supports. Capability: List of capabilities against which the called operation needs to be authorized. |
@Required | @Path("/reports" ) @GET @Produces( "application/vnd.jssdk.reports+xml;version=1") public Response getAllReports( @Required @QueryParam("temperature-unit") String tempUnit, @QueryParam("device-id") int deviceId) |
Applicable on the parameters of the REST method .
This annotation is used for indicating that the query
parameter is mandatory. It is read by the info service and
displayed in its output later. Refer to the example given
here. In this example, the @Required annotation
emphasize that the 'temperature-unit' query parameter is
mandatory while the 'device-id' is optional. Variables: None |