Introduction
ProForma provides an API to make it easier for our customers to access their data. This version 1.1 the API includes the Export API and a number of new form related features in the Form API. We plan to add more features to the Form API in future versions.
Availability
The API is available in Jira Server and Jira Data Center but it is not available in Jira Cloud. If you are a Cloud customer who would find this API useful, please contact us to discuss whether we can find a solution for you.
The ProForma Customer API is available in the following versions of ProForma:
ProForma Customer API | ProForma Version |
|---|---|
v1.0.0 | v8.2.0 and later |
v1.1.0 | v8.4.0 and later |
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.
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 Export 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.
Accessing the Form API requires a Jira user with the appropriate browse, edit or project admin permissions relevant to the specific API.
Users 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.
