Upgrade Notes
REST API version changes
The REST API changes from time to time. We try to keep these changes as minimal as possible, but at some point technical debt needs to be dealt with. See in the version sections below which changes made to the API on the respective app version:
v2.9.0 to v2.9.1
No breaking changes.
v2.8.1 to v2.9.0
No breaking changes.
v2.8.0 to v2.8.1
No breaking changes.
v2.7.2 to v2.8.0
No breaking changes.
breaking:
-
non-breaking:
[CE-102] Improved REST API Validation Message on Duplicate Option
Affected Endpoints:GET /maintenance/event_log_entries/truncate_schedule
POST /user/customfields/{customFieldId}/contexts/default/options
PUT /user/customfields/{customFieldId}/contexts/default/options/{optionId}
POST /user/customfields/{customFieldId}/contexts/{contextId}/options
PUT /user/customfields/{customFieldId}/contexts/{contextId}/options/{optionId}
POST /user/customfields/{customFieldId}/contexts/default/options/{optionId}/childoptions
PUT /user/customfields/{customFieldId}/contexts/default/options/{optionId}/childoptions/{childOptionId}
POST /user/customfields/{customFieldId}/contexts/{contextId}/options/{optionId}/childoptions
PUT /user/customfields/{customFieldId}/contexts/{contextId}/options/{optionId}/childoptions/{childOptionId}
Summary: No structural changes to any endpoints. Release v2.8.0 brings additional Validation Messages on create and update of customfield options. Once you send a duplicate value you will receive an additional validation message showing the id of the existing option. See [CE-102] for all details.
v2.7.1 to v2.7.2
No breaking changes.
v2.7.0 to v2.7.1
No breaking changes.
v2.6.0 to v2.7.0
No breaking changes.
v2.5.5 to v2.6.0
No breaking changes.
v2.5.4 to v2.5.5
Breaking changes!
breaking:
[CE-91] REST API Explorer: URL of API Definition swagger.json changed:
OLD /plugins/servlet/customfieldeditorplugin/restapi/swagger.json
- HTTP 302 redirects to new URL -NEW /jira/rest/jiracustomfieldeditorplugin/1/api_specification/swagger_json
non-breaking:
- -
v2.5.3 to v2.5.4
No breaking changes.
breaking:
-
non-breaking:
[CE-89] REST API: new Auto-Truncate Event Log Job Endpoints
New Endpoints:GET /maintenance/event_log_entries/truncate_schedule
PUT /maintenance/event_log_entries/truncate_schedule
Summary: No structural changes to any endpoints. Release v2.5.4 brings an opt-in feature [CE-89]. If the Auto-Truncate Event Log Job is activated it will run at certain time intervals and clear the Event Log table.
v2.5.2 to v2.5.3
No breaking changes.
v2.5.1 to v2.5.2
No breaking changes.
v2.5.0 to v2.5.1
No breaking changes.
v2.4.0 to v2.5.0
No breaking changes.
v2.3.0 to v2.4.0
No breaking changes.
breaking:
-
non-breaking:
[CE-14] Allow delete option only for administrators
Summary: No structural changes to any endpoints. Release v2.4.0 brings an opt-in feature [CE-14]. If the setting is active all delete option endpoints return HTTP 403 for non-administrators, meaning only Jira administrators can delete options.
v2.2.0 to v2.3.0
No breaking changes.
v2.1.0 to v2.2.0
No breaking changes.
v2.0.1 to v2.1.0
No breaking changes.
v2.0.0 to v2.0.1
No breaking changes.
v1.9.0 to v2.0.0
No breaking changes.
breaking:
-
non-breaking:
[CEP-71] REST API new incremental Permission update Endpoint (HTTP PATCH)
[CEP-69] REST API new combined get customfield, context and defaultOption Endpoint (HTTP GET)
[CEP-72] REST API old full Permission update Endpoint (HTTP PUT) now enforces users must exist (returns validation errors if not).
[CEP-68] REST API user and admin customfield lists: Introducing paginable, filterable and orderable results. (backwards compatible but with deprecations)
deprecations:
- GET /user/customfields and /admin/customfields for old un-paginated results are deprecated and will be removed in future releases. See [CEP-68].
Summary: No structural changes to any endpoints. Release v2.0.0 brings all the performance optimizations needed for Data Center compatibility. Only deprecations for non-paginated customfield list endpoints (see above).
v1.8.0 to v1.9.0
No breaking changes.
v1.7.1 to v1.8.0
Breaking changes!
breaking:
non-breaking:
[CEP-58] REST API: Change of existing option should work even if only case is changed
Summary: No structural changes to any endpoints. All Endpoints still have the same URLs and same JSON Schemas for Request and Response. All Endpoints now use HTTP 400
for most of the errors. HTTP 406
removed. HTTP 412
only used for version compatibility errors. HTTP 500
only used for unexpected errors.
v1.5.0 to v1.7.1
No breaking changes.
v1.4.0 to v1.5.0
Breaking changes!
breaking:
[CEP-36] Rest-API: All Endpoints will return
HTTP 403
instead ofHTTP 500
on non existing custom field id.
non-breaking:
[CEP-31] Rest-API: Provide associated projects and issue types info for
/*/customfields/{id}/contexts
Endpoint.
v1.3.0 to v1.4.0
No breaking changes.
v1.2.3 to v1.3.0
No breaking changes.
breaking:
-
non-breaking:
[CEP-INT-8] base url is now
/1/
not/1.2/
anymore. But will be backwards compatible. Please use/rest/jiracustomfieldeditorplugin/1/*
as base URL now.[CEP-INT-8] removed the "
/1.1/
Compatibility Mode" completely. Please use/rest/jiracustomfieldeditorplugin/1/*
as base URL now.[CEP-12] added
/extended
Endpoints for admin context permissions that display users fullname in userlists.
v1.2.2 to v1.2.3
No breaking changes.
v1.2.1 to v1.2.2
No breaking changes.
v1.2.0 to v1.2.1
You don't really need to do anything. Everything should work as before since it is just a bugfixing release which also brings the new context security feature. See the administrator guide for more details.
v1.0.0/1.1.0 to v1.2.0
You are advised to migrate to the new v1.2 URLs but you can use the v1.1 compatibility mode until you fully migrated. Here are the changes to the API from v1.1 to v1.2:
new baseUrl (with version
/1.2/
)the URL pattern changed for all endpoints. See the the above REST-API-Endpoint-Documentation.
CustomFieldId is now
Long
(1234) notString
(customfield_1234) anymore.childOptions are removed from GET Options Resource response. Use separate Request on GET childOptions Resource now.
XML Support is removed completely. Use JSON as body-payload instead.
Error Responses are a little different and there are more distinct Response codes. See the the above REST-API-Endpoint-Documentation for all details.
Added Support for Field Contexts (with contextIDs or defaultContext).
Added alphabetical Sorting Endpoint for Options and childOptions.
Added Setting of default Value Endpoint.
Added a REST API Explorer on URL
http://server:port/jira/plugins/servlet/customfieldeditorplugin/restapi/
. You can trigger API Calls to the API directly in the BrowserAdded admin Endpoints to set permissions and list customfields (for jira-administrator only)