Serving a WADL document for the resources

A developer might not want to expose the Web Application Description Language (WADL) document via an OPTIONS request to limit the amount of information a third party can gather about a service. By providing less information, security through obscurity may be achieved.

By default, a WADL document can be requested for a particular resource by invoking an HTTP OPTIONS request for any Java API for RESTful Web Services (JAX-RS) URL. We can issue an OPTIONS request with most HTTP clients.

We can also build our own WADL document using the org.apache.wink.common.model.wadl.WADLGenerator. WADLGenerator builds a JAXB annotated object model so we can return it as an entity response in an @OPTIONS resource method. If we want a service document for all the classes in the application, we can use the WADLGenerator to create a WADL representation. The service document can help enhance the understanding.

In the following example, we can use the WADLGenerator to build a JAXB model of the resources. We can then return the JAXB model for clients to consume.

1. We can inject the Application subclass containing all your resource classes. Then we can pass in the classes to the WADLGenerator to generate the classes.

2. Return the org.apache.wink.common.model.wadl.Application class, which is a JAXB annotated object. The JAX-RS MessageBodyWriter for JAXB annotated types are used to serialize the WADL document to the client.

Example

The following example illustrates a basic resource with an OPTIONS request:

@javax.ws.rs.Path("myexample")
public class MyResource {
    @Context
    javax.ws.rs.core.Application app;
         @javax.ws.rs.OPTIONS
    @Produces("application/vnd.sun.wadl+xml")
    public org.apache.wink.common.model.wadl.Application getOptions() {
        org.apache.wink.common.model.wadl.Application wadlAppDoc = new WADLGenerator().generate("", app.getClasses());
        /* modify the wadlAppDoc JAXB model to add additional information */
        return wadlAppDoc;
    }
} 

Related tasks

Disable generation of WADL documents for HTTP OPTIONS requests

Web services specifications and APIs