ProForma API Documentation
- Simon Herd
Introduction
ProForma provides an API to make it easier for our customers to access their data. In this version 1.0 the API is focussed on data export, allowing you to get all your ProForma data out for backup or use in external systems. We plan to add more features in future versions.
Availability
The API is available in Jira Server and Jira Data Center but it is not available in Jira Cloud. I
The ProForma Customer API is available in the following versions of ProForma:
Version policy
The ProForma Customer API uses semantic versioning. This means that we strive to maintain backwards compatibility, and new features will be added to the API without breaking existing functionality. All changes to the API will require a new version.
Bug fixes are treated a 'patch' version. This is indicated by the third digit of the version number, eg 1.0.0 → 1.0.1
New features which do not change existing functionality are treated as a 'minor' version. This is indicated by the second digit of the version number, eg 1.0.0 → 1.1.0
New features which do change existing functionality are treated as a 'major' version. This is indicated by the first digit of the version number, eg 1.0.0 → 2.0.0. If we release a new major version it is our intention that the previous version will still be available and be maintained until customers can migrate to the new one.
Jira Permissions
Export Data API
In order to access the ProForma Export API, a user must have the ProForma: Export All Data global permission (Jira Settings > Systems > Global Permissions). No groups are assigned to this permission by default. Once this permission is given, members of the group will be able to call export APIs in ProForma with full access to all form and issue data.
Customer API
Any user with permission to edit an issue can call the ProForma Customer API.
Authentication
The ProForma Customer API is a Jira REST API, which means it uses the same authentication methods as the Jira REST API. Accessing the API requires a Jira user with the permission "ProForma: Export All Data". This is a global permission which a Jira administrator can add to any user. By default no users are granted this permission (not even Jira administrators) so the API is effectively off by default.
A user with the ProForma: Export All Data permission can use either of the two methods Jira provides to authenticate for APIs:
OAuth 1.0a
Atlassian recommends that you use OAuth 1.0a rather than basic authentication, and we do too. Refer to Atlassian OAuth documentation for how to authenticate using OAuth.
Basic authentication
If you just want to try out the API quickly before making more formal use of it then you may wish to use basic authentication. Refer to Atlassian basic authentication documentation for how to do this.
Export Data Permission
In order to access the ProForma API, a user must have the ProForma: Export All Data global permission (Jira Settings > Systems > Global Permissions). No groups are assigned to this permission by default. Once this permission is given, members of the group will be able to call export APIs in ProForma with full access to all form and issue data.
