Upgrade Notes

Good, better, best. Never let it rest. 'Til your good is better and your better is best.

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:

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:

    • [CEP-56] REST API: Simplify Errors - Remove HTTP 406 - Migrate to HTTP 400.

    • [CEP-57] REST API: Improve Error Handling for ChildOption Endpoints of Cascading Select fields.

  • 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 of HTTP 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) not String (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 Browser

  • Added admin Endpoints to set permissions and list customfields (for jira-administrator only)