Step 8 of 10 Providing REST API access to plugin services and settings

Goal

In this step, you'll create a REST API that will allow you to access your subject mapping data and set the values on your subject mapping preferences.

REST API

The last bit of implementation is the REST API controller. In the Spring context, controllers are classes that accept requests from outside the system and figure out how to translate from the format of that request to the particular calls that are available on the service layer. For a REST API, this means accepting HTTP requests and turning those into calls to the service to create, update, and retrieve the data managed by the relevant service.

Much like Spring and Hibernate, REST APIs are an entire field of discussion in and of themselves. The most succinct description of a REST API is simply a way to call functions on a service by making requests to a web service rather than requiring your code to run within the same process space as the service you're calling.

For more information on REST, you can find a very broad description on the Wikipedia page for "representational state transfer". Here's a good general introduction to REST. There's also a good introduction to creating a REST service in Spring, with much more detail available in the Spring Framework reference documentation about REST controllers.

Here's a stripped-down implementation of a REST controller for the subject mapping service:

@XapiRestController
@RequestMapping(value = "/subjectmapping")
public class SubjectMappingRestController extends AbstractXnatRestApi {
    @RequestMapping(method = RequestMethod.GET)
    public ResponseEntity<List<SubjectMapping>> getEntities() {
        // Do stuff here.
    }

    @RequestMapping(method = RequestMethod.POST)
    public ResponseEntity<SubjectMapping> createEntity(@RequestBody final SubjectMapping entity) {
        // Do stuff here.
    }

    @RequestMapping(value = "{id}", method = RequestMethod.GET)
    public ResponseEntity<SubjectMapping> getEntity(@PathVariable final Long id) {
        // Do stuff here.
    }

    @RequestMapping(value = "{id}", method = RequestMethod.PUT)
    public ResponseEntity<Void> updateEntity(@PathVariable final Long id,
                                             @RequestBody final SubjectMapping entity) {
        // Do stuff here.
    }

    @RequestMapping(value = "{id}", method = RequestMethod.DELETE)
    public ResponseEntity<Void> deleteEntity(@PathVariable final Long id) {
        // Do stuff here.
    }

    @Autowired
    private SubjectMappingService _service;
}

Most of this implementation is not specific to creating a REST controller for XNAT, so we won't go into a great deal of detail about it, but will point out a few important items as well as the XNAT-specific features:

• The @XapiRestController annotation replaces the standard Spring @RestController annotation. The main purpose for this is to allow this controller to be located and included in the XAPI Swagger documentation. This implementation doesn't show the various Swagger annotations, but the version in the attached zip file does include these.
• The @RequestMapping annotation on the class declaration specifies the top-level folder for URLs when accessing this command. All XAPI REST controllers are already located under the /xapi path, meaning that all functions from this controller will start with /xapi/subjectmapping.
• The SubjectMappingRestController extends the AbstractXapiRestController class, which provides a number of commonly used methods for integrating with XNAT.
• Your subject mapping service is "injected" into the REST API implementation by using the @Autowired annotation. This is actually set by Spring as a result of the component scanning pass, which, again, we'll discuss shortly.

Completed!

You've added a custom REST controller and REST API documentation.

Go to the next step