Atlassian Developer Network

REST Plugin Module Type

You can use the REST module type to create plugin points easily in Atlassian applications, by exposing services and data entities as REST APIs.

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.

Plugin Framework 2 Only
The REST plugin module described below is available only for OSGi-based plugins using version 2.2 or later of the Atlassian Plugin Framework.

On this page:

Purpose of this Module Type

REST plugin modules enable you to expose services and data as REST resources.

Configuration

The root element for the REST plugin module is rest. It allows the following attributes and child elements for configuration.

Attributes

Name Required Description Default
key 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 fred in a plugin with key com.example.modules will have a complete key of com.example.modules:fred. N/A
path The path to the REST API exposed by this module. For example, if set to /api, the REST API will be available at http://localhost:8080/context/rest/api/1.0, where 1.0 is the version of the REST API. N/A
version 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. major.minor.micro.qualifier where major, minor and micro are integers. N/A

Elements

Name Required Description Default
description   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. N/A

Example

Here is an example atlassian-plugin.xml file containing a single public component:

<atlassian-plugin name="Hello World" key="example.plugin.helloworld" plugins-version="2">
    <plugin-info>
        <description>A basic REST module test</description>
        <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
        <version>1.0</version>
    </plugin-info>

    <rest key="helloWorldRest" path="/helloworld" version="1.0">
        <description>Provides hello world services.</description>
    </rest>
</atlassian-plugin>

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.

See Overview of REST Implementation using the REST Plugin Module Type.

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:

  1. Develop your JAX-RS resources, using the annotations @Path, @Provider, etc.
  2. Bundle your resource classes in your plugin JAR file, along with the plugin descriptor atlassian-plugin.xml.
  3. Deploy your plugin to the application.

See How to Build an Atlassian Plugin and Creating your Plugin Descriptor.

Accessing your REST Resources

Your REST resources will be available at this URL:

http://host:port/context/rest/helloworld/1.0
  • host and port define the host and port where the application lives.
  • context is the servlet context of the application. For example, for Confluence this would typically be confluence.
  • helloworld is the path declared in the REST module type in the plugin descriptor.
  • 1.0 is the API version.

If 1.0 is the latest version of the helloworld API installed, this version will also be available at this URL:

http://host:port/context/rest/helloworld/latest

How the REST Plugin Module Finds your Providers and Resources

The REST plugin module scans your plugin for classes annotated with the @Provider and @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.

The REST plugin module will not scan a library bundled with your plugin, typically bundled in the META-INF/lib directory of the JAR. So make sure you put all providers and resources at the top level in your plugin JAR.

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 not always convenient.

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:

http://host:port/context/rest/helloworld/latest/myresource

I have two options:

  • Option 1: Use the HTTP Accept header set to application/json.
  • Option 2: Simply request the resource via this URL: 
    http://host:port/context/rest/helloworld/latest/myresource.json

If I want content of type application/xml, I will simply change the extension to .xml. Currently the REST plugin module supports only application/json and application/xml.

Working with JSON in Firefox

A handy tool: The JSONView add-on for Firefox allows you to view JSON documents in the browser, with syntax highlighting. Here is a link to the Firefox add-on page.

References

RELATED TOPICS

Plugin Tutorial - Writing REST services
How to Build an Atlassian Plugin
Overview of REST Implementation using the REST Plugin Module Type
Atlassian REST API Design Guidelines version 1
Guidelines for Atlassian REST API Design
Atlassian Plugin Framework Documentation

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Comments (4)

 

  1. Oct 17

    Dmitry Kashin says:

    How to enable it in Confluence? Now I see *Error:*Support for this module is not...

    How to enable it in Confluence? Now I see *Error:*Support for this module is not currently installed.

    even in 3.1-m5-r7 :(

    1. Nov 03

      Dmitry Kashin says:

      Anyone?

      Anyone?

      1. Nov 03

        William Morrell says:

        I was able to use it by adding the following as plugins to my Confluence install...

        I was able to use it by adding the following as plugins to my Confluence installation:

        1. google-collections-1.0-rc1.jar from <https://maven.atlassian.com/public/com/atlassian/bundles/google-collections/1.0-rc1/>
        2. atlassian-template-renderer-api-1.0.3.jar from <https://maven.atlassian.com/public/com/atlassian/templaterenderer/atlassian-template-renderer-api/1.0.3/>
        3. atlassian-template-renderer-velocity16-plugin-1.0.3.jar from <https://maven.atlassian.com/public/com/atlassian/templaterenderer/atlassian-template-renderer-velocity16-plugin/1.0.3/>
        4. atlassian-rest-module-1.0.6.jar from <https://maven.atlassian.com/public/com/atlassian/plugins/rest/atlassian-rest-module/1.0.6/>

        Then redeploying the plugin using the REST module. See AMPS-186.

  2. Jan 13

    Nick Pellow says:

    In the section titled: Including the REST Module Plugin Type in your Project ,&n...

    In the section titled: Including the REST Module Plugin Type in your Project , 

    you could also add an example of what must be added in the plugin's pom.xml for this to happen.

    e.g. for JIRA, I included the following, (which is possibly incorrect for other plugins)

            <dependency>
            <groupId>com.atlassian.jira</groupId>
            <artifactId>jira-rest-plugin</artifactId>
            <version>${jira.version}</version>
            <scope>provided</scope>
        </dependency>

    Also, the link in that section: http://docs.atlassian.com/atlassian-rest/ doesn't provide much help.