REST Annotations

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.

REST Annotations

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.

@Path

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:

  • Resource at the class level would have @Path("/"). This is the default annotation at the class level.
  • Resource at the API level would have @Path("Countries") annotation.
  • 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).

    Annotations Used to Map HTTP Operations or Commands to an API

    The following method-level annotations are used to map an HTTP operation or command to an API.

    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.

    REST API Stub

    
    
    @Path("countries")  // (1)
    
    @GET // (2)
    
    @Produces("application/vnd.jssdk.world-cities.countries+xml;version=1") //(3)
    
    public Countries getCountries();
    
    
    
    

    REST API Invocation

    
    
    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)
    
    
    
    

    Explanation

    1. Specifies that the REST URI is accessed through the Countries Resource URI.
    2. This statement maps to the HTTP GET request.
    3. Media type that is accepted by this resource (maps to the HTTP Accept header.)
    4. Specifies an HTTP GET request to access the resource "Countries" that has a class-level REST resource as ("/world").
    5. The Accept header is mapped to the @Produces annotation specified in Step 3.

    Media Type Annotations

    There are two media type annotations: @Consumes and @Produces.

    @Consumes

    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:

    @Produces

    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.

    Junos Space Annotations for REST

    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:
  • APPLICATION(default): The String value present in the href field is prefixed with the URL of service being accessed.
  • GLOBAL: The Resource href is created from the String value of href field is present in this annotation.
  • URI: The href is built from the URL being accessed.


  • 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:
  • APPLICATION(default): The String value present in the href field is prefixed with the URL of the service being accessed.
  • GLOBAL: The resource href is created from the String value of the  href field present in this annotation.
  • URI: The href is built from the URL being accessed.


  • 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