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:

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:

    • [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.

    • [CEP-INT-8] removed the "v1.1 Compatibility Mode" completely.

    • [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)