Resource Paths

Resource Path Description

Resource URIs are composed of the following elements:

    <context-root> + <service-root> + <method-path>

For example, in /api/jssdk/hello-world/world/countries:

    <context-root> = /api/jssdk/hello-world
    <service-root> = /world
    <method-path> = /countries

where <context-root-path> is the path specified in the application.xml file. The entry in application.xml maps the <context-root-path> to the Web Service War which contains the restified resource. For example, the entry below maps the context-root /api/jssdk/hello-space to the Web Service WAR file HelloSpaceWebSvc.war, which is built in the HelloSpaceWebSvc project.

<module>
    <web>
      	<web-uri>HelloSpaceWebSvc.war</web-uri>
      	<context-root>/api/jssdk/hello-space</context-root>
    </web>
<module>


The <service-root> path is always listed at the top of the service resource interface file with the @Path annotation.  For example, the one for HelloSpace looks like this:

@Path("")
public interface HelloSpaceRest {
...
}

The listed <service-root> listed in HelloSpaceRest.java Web Service interface is an empty string (""), which is equivalent to "/".

In that file, you will also find method paths, which are also listed with the @Path annotations. For example:

@Path("/devices")

refers to the "/devices" method path, so the complete path for this method is:

/api/jssdk/hello-space/devices.

Primary/Secondary Resources

Resources (or services) that share the same Context Root and Service Root paths are called primary/secondary resources. For example, tomorrow you might decide that you want to expose another collection "/vlans" in HelloSpace, and you want to share the same prefix /api/jssdk/hello-space. Furthermore, you no longer want to use the same Java interface that you used for /devices. Therefore, you will use the wizard to create a new resource, but you will reuse the <context-root> and the <service-root> paths of the existing resource.

The wizard allows you to have two different resources that share the same context root and service root paths. The first resource that you created (the one containing the /devices method) will be the primary resource, and all subsequent resources will be the secondary resources. The primary resource will be the only resource to contain the getRoot() method because there can only be one getRoot() method per resource root path (context-root + service-root). The primary resource will also be the only resource, which contains all the root-level HATEOAS method links for all the resources (both secondary and primary links). This is done because when the user navigates to the resource root path, they will see all the links for all the resources sharing that path.

If a secondary resource is deleted, all its root-level HATEOAS method links will be removed from the primary resource.

When the primary resource is deleted, all it's root-level HATEOAS method links will migrate to another secondary resource, which will subsequently become the new primary resource.

Master Slave Resources and Versioning

When a new version of any resource is created, all the root-level HATEOAS links are copied from the previous version to the new version. In addition, the new version might also contain newly created root-level HATEOAS links. Therefore, if I navigate to the previous version's root, you will only see all the HATEOAS links for the previous version and all the versions before it, but not for the current version.

When a new version of a resource is created, and there are primary/secondary resources, all the new root-level HATEOAS links will always be created in the primary resource. For example, if you have v1 of a primary and both a v1 and v2 of a secondary, the links of the v2 will be created in v1 of Master, so when you navigate to the primary's root-level URI, you will have links for both the secondary and primary.