REST Module Type
Purpose of the REST Plugin Module
You can use the REST plugin module to expose services and data entities as REST APIs. The Atlassian REST plugin module is bundled with our applications.
REST APIs provide access to resources via URI paths. To use a REST API, your plugin or script will make an HTTP request and parse the response. You can choose JSON or XML for the response format. Your methods will be the standard HTTP methods like GET, PUT, POST and DELETE. Because the REST API is based on open standards, you can use any web development language to access the API.
Mapping the URL to a Resource
A REST resource is exposed at a URL such as this:
Here's how the parts of the URL are composed and used:
http://myhost.com:port– The operating system directs the request to the application server (e.g. Tomcat) that handles the specified port.
/myapp– Tomcat directs the request to the application myapp.
/rest– The application's web.xml deployment descriptor file maps the URLs to the relevant servlets. So in this case, it maps /rest to our REST servlet, which points to our REST plugin module type.
/api-name/api-version– Now the REST plugin module takes over. The relevant part of the URL (
api-version) are defined as the
atlassian-plugin.xmlfile. For example:
/resource-name– The final part of the URL mapping (
resource-nameand sub-elements) is done via annotations on the class, used to declare the URI path, the HTTP method and the media type. Jersey (based on JAX-RS) reads the
@Pathannotations and maps them to classes and methods, so that we know which method is called for each REST resource and method. See the Jersey documentation.
About JAXB Annotations
For example a Java
User object with JAXB annotations may look something like this:
The XML response content for user John Smith would be:
By default, on conversion the XML element name will be the same as the object name. Alternatively, you can add the XML element name to the annotation. Something like this:
@XmlRootElement(name="principal"). There are specific annotations for arrays, etc. See JAXB's documentation for more details on this.
Jersey also handles JSON based on the same JAXB objects as in the example above. The JSON for the example would be:
A trivial REST service class with a single URL returning an instance of
User would look like this:
Configure the Module in the Plugin Descriptor
The root element for the REST plugin module is
rest. It allows the following attributes and child elements for configuration.
The identifier of the plugin module, i.e. the identifier of the REST module. This key must be unique within the plugin where it is defined. Sometimes you will need to uniquely identify a module. Do this with the complete module key. A module with key
The path to the REST API exposed by this module. For example, if set to
This is the version of the REST API. This is not the same thing as the plugin version. Different versions of the same API can be provided by different plugins. Version numbers follow the same pattern as OSGi versions, i.e.
The description of the plugin module, i.e. the description of the REST module. The 'key' attribute can be specified to declare a localisation key for the value instead of text in the element body.
The package from which to start scanning for resources and providers. Can be specified multiple times. Defaults to scanning the whole plugin. Since 2.0
Determines when the filter is triggered. You can include multiple
Default: Filter will be triggered on
Here is an example
atlassian-plugin.xml file containing a single public component:
Notes on REST API and Plugin Development
JAX-RS and Jersey
Here is some information to be aware of when developing a REST plugin module:
- The REST module is based on JAX-RS. Specifically, it uses Jersey, which is the JAX-RS reference implementation.
- The REST module is based on version 1.0.2 of Jersey.
- Jersey is configured to use all its default providers, but you should be able to change the configuration by adding your own providers in your plugin. For example, you may want to enhance your JSON.
Including the REST Plugin Module into your Project
You can include the REST plugin module as a Maven dependency from our Maven repository.
Developing your REST API as an Atlassian Plugin
To develop a REST API and deploy it into an Atlassian application, you will follow the same process as for any other Jersey application:
- Develop your JAX-RS resources, using the annotations
- Bundle your resource classes in your plugin JAR file, along with the plugin descriptor
- Deploy your plugin to the application.
Accessing your REST Resources
Your REST resources will be available at this URL:
portdefine the host and port where the application lives.
contextis the servlet context of the application. For example, for Confluence this would typically be
helloworldis the path declared in the REST module type in the plugin descriptor.
1.0is the API version.
1.0 is the latest version of the helloworld API installed, this version will also be available at this URL:
How the REST Plugin Module Finds your Providers and Resources
The REST plugin module scans your plugin for classes annotated with the
@Path annotation. The
@Path annotations can be simply declared on a method within a class and do not need to be present at the entity level.
For those not familiar with the JAX-RS specification, the @Path annotation can be declared at a package, class, or method level. Furthermore, their effects are cumulative. For example, if you define this at the package level:
then this at the class level:
then this at the method level:
The final URL would be for the helloWorld plugin above:
- The REST plugin module will not scan a library bundled with your plugin, typically bundled in the
META-INF/libdirectory of the JAR. So make sure you put all providers and resources at the top level in your plugin JAR.
- Only one resource method can be bound to the root "/" path.
Easy Way to Request JSON or XML Response Format
When using JAX-RS (and Jersey), the standard way to specify the content type of the response is to use the HTTP Accept header. While this is a good solution, it's not always a convenient one.
The REST plugin module allows you to use an extension to the resource name in the URL when requesting JSON or XML.
For example, let's assume I want to request JSON data for the resource at this address:
I have two options:
- Option 1: Use the HTTP Accept header set to
Option 2:Simply request the resource via this URL:
If I want content of type
application/xml, I will simply change the extension to
.xml. Currently the REST plugin module supports only
Working with JSON in Firefox
Differences in JSON and XML rendering of REST responses
By default, JSON responses include any object fields which are explicitly annotated with a JAXB annotation, while XML responses include public fields and fields with public getters.
To get the same behaviour for JSON you need to either annotate each field with
@XmlAttribute, or annotate the class or package with
- JAX-RS (JSR311) home page
- Jersey home page
- 1.0.3 API (https://jersey.github.io/apidocs/1.0.3/jersey/index.html) (implements JAX-RS 1.0)
- Configuring JSON for RESTful Web Services in Jersey 1.0