Expose ReST services via OSGi

To expose a REST service via OSGi, follow these steps:

Define an interface, containing java jax-rs annotations.
Define a class, implementing that interface. Create an OSGi bundle that exports a service with the interface from above.

Define a REST interface

First, create a public interface that must contain jax-rs annotations.

@Path("/datachoices") (1)
public interface DataChoiceRestService {

    @POST (2)
    @Path("status")
    @Consumes({MediaType.APPLICATION_JSON})
    Response setStatus(@Context HttpServletRequest request, UsageStatisticsStatusDTO dto);

    @GET
    @Produces(value={MediaType.APPLICATION_JSON})
    UsageStatisticsReportDTO getUsageStatistics();
}

1	Each REST interface must either have a `@Path` or `@Provider` annotation. Otherwise, it is not considered a REST service.
2	Use jax-rs annotations, such as `@Post, @GET, @PUT, @Path`, etc., to define the REST service.

Implement a REST Interface

A class must implement the REST interface.

The class may or may not repeat the jax-rs annotations from the interface. This is purely for readability. Changing or adding different jax-rs annotations on the class will not have any effect.

public class DataChoiceRestServiceImpl implements DataChoiceRestService {

    @Override
    public Response setStatus(HttpServletRequest request, UsageStatisticsStatusDTO dto) throws ServletException, IOException {
        // do something
        return Response.accepted().build();
    }

    @Override
    public UsageStatisticsReportDTO getUsageStatistics() {
       return null;
    }
}

Export the REST Service

Finally, you must export the REST service via the bundlecontext. Achieve this by using either an Activator or the blueprint mechanism.

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	       xsi:schemaLocation="
                http://www.osgi.org/xmlns/blueprint/v1.0.0
                http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
">
    <bean id="dataChoiceRestService" class="org.opennms.features.datachoices.web.internal.DataChoiceRestServiceImpl" /> (1)
    <service interface="org.opennms.features.datachoices.web.DataChoiceRestService" ref="dataChoiceRestService" > (2)
        <service-properties>
            <entry key="application-path" value="/rest" /> (3)
        </service-properties>
    </service>

</blueprint>

1	Create the REST implementation class.
2	Export the REST service.
3	Define where the REST service will be exported, e.g., `/rest`, `/api/v2`. You can also use completely different paths. If not defined, `/services` is used.

For a full working example, refer to the datachoices feature.