Announcement — Various fixes to Account, User, and Team schemas

Summary

We are fixing discrepancies between the documented and actual objects returned by some of our APIs.

On Jul 22, 2022, we will change the schema definitions for the User, Team and Account objects documented in our swagger.json and at developer.atlassian.com to reflect the data returned from our APIs.

Why we are changing the Account, User, and Team schemas?

The previous schemas did not accurately reflect the data returned by our API, and we are updating the schemas to correct the discrepancies.

Where the Bitbucket Cloud APIs have previously shown that they return the Account schema object, they can return either the User or the Team subtype. The schemas of both the User and Team subtypes inherit the Account definition and should return all the fields defined in the Account object schema.

Changes to the existing schema

We have updated or removed some properties in the schema definitions for the User, Team, and Account objects; to reflect the properties shared and returned by our APIs. The properties that have been changed or removed were not marked as required.

Changes to some endpoints

We have also updated the swagger definitions attached to a number of endpoints. Many of these endpoints previously stated that they return a User object, but have been updated to state that they return an Account object. This reflects the current API behavior. The reason for this change is that the endpoints currently are able to return either User or Team objects, so Account is a more correct representation.

We have also taken the chance to fix a number of endpoints which have no attached swagger, or have erroneously attached swagger definitions.

What action is required?

These changes should require little or no action by developers. If you use our swagger.json file to auto-generate client code, you may wish to regenerate your client code. As the actual returned payloads from our APIs are not changing, we're not expecting anyone to be impacted by these changes.

Which schema objects are affected?

Comment changes

• The user is now of type Account instead of type User.

Commit Comment changes

• The commit field refers to type Commit which has changes (See Commit changes)

Commit changes

• The author is now of type Account instead of type User.

Issue Change changes

• The user is now of type Account instead of type User.
• The issue field refers to type Issue which has changes (See Issue changes)

Issue Comment changes

• The issue field refers to type Issue which has changes (See Issue changes)
• The parent type Comment has changes (See Comment changes)

Issue changes

• The assignee is now of type Account instead of type User.
• The reporter is now of type Account instead of type User.

Paginated Commit Comments changes

• The values array field refers to type Commit Comment which has changes (See Commit Comment changes)

Paginated Issues changes

• The values array field refers to type Issue which has changes (See Issue changes)

Paginated Issue Comments changes

• The values array field refers to type Issue Comment which has changes (See Issue Comment changes)

Paginated Log Entries changes

• The values array field refers to type Issue Change which has changes (See Issue Change changes)

Paginated Pull Requests changes

• The values array field refers to type Pull Request which has changes (See Pull Request changes)

Paginated Pull Request Comments changes

• The values array field refers to type Pull Request Comment which has changes (See Pull Request Comment changes)

Pull Request Comment changes

• The parent type Comment has changes (See Comment changes)

Pull Request changes

• The participants array field refers to type Participant which has changes (See Participant changes)

Participant changes

• The user is now of type Account instead of type User.

Which API endpoints are affected?

The following lists show all the endpoints that have changed, along with the fields that have changed in the API. This announcement is purely to indicate that the APIs schema has been updated to match the current API return types. There's no change to the response or request bodies for any of our APIs.

Commits endpoints

• POST /2.0/repositories/{workspace}/{repo_slug}/commit/{commit}/approve — See Participant changes
• GET /2.0/repositories/{workspace}/{repo_slug}/commit/{commit}/comments/{comment_id} — See Commit Comment changes
• POST /2.0/repositories/{workspace}/{repo_slug}/commit/{commit}/comments — See Commit Comment changes
• GET /2.0/repositories/{workspace}/{repo_slug}/commit/{commit}/comments — See Paginated Commit Comments changes

Issue tracker endpoints

• GET /2.0/repositories/{workspace}/{repo_slug}/issues — See Paginated Issues changes
• POST /2.0/repositories/{workspace}/{repo_slug}/issues — See Issue changes
• DELETE /2.0/repositories/{workspace}/{repo_slug}/issues/{issue_id} — See Issue changes
• GET /2.0/repositories/{workspace}/{repo_slug}/issues/{issue_id} — See Issue changes
• PUT /2.0/repositories/{workspace}/{repo_slug}/issues/{issue_id} — See Issue changes
• GET /2.0/repositories/{workspace}/{repo_slug}/issues/{issue_id}/changes — See Paginated Log Entries changes
• POST /2.0/repositories/{workspace}/{repo_slug}/issues/{issue_id}/changes — See Issue Change changes
• GET /2.0/repositories/{workspace}/{repo_slug}/issues/{issue_id}/changes/{change_id} — See Issue Change changes
• GET /2.0/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments — See Paginated Issue Comments changes
• POST /2.0/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments — See Issue Comment changes
• DELETE /2.0/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments/{comment_id} — Removed body parameter schema which was erroneously set.
• GET /2.0/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments/{comment_id} — See Issue Comment changes
• PUT /2.0/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments/{comment_id} — See Issue Comment changes

Pullrequests endpoints

• GET /2.0/repositories/{workspace}/{repo_slug}/default-reviewers - 200 response now has type Paginated Accounts. Previously, this was erroneously not set.
• GET /2.0/repositories/{workspace}/{repo_slug}/default-reviewers/{target_username} - 200 response now has type Account. Previously, this was erroneously not set.
• PUT /2.0/repositories/{workspace}/{repo_slug}/default-reviewers/{target_username} - 200 response now has type Account. Previously, this was erroneously not set.
• POST /2.0/repositories/{workspace}/{repo_slug}/pullrequests - See Pull Request changes
• GET /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id} - See Pull Request changes
• PUT /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id} - See Pull Request changes
• POST /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/decline - See Pull Request changes
• POST /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/merge - See Pull Request changes
• GET /2.0/pullrequests/{selected_user} - See Paginated Pull Requests changes
• GET /2.0/repositories/{workspace}/{repo_slug}/pullrequests - See Paginated Pull Requests changes
• POST /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/approve - See Participant changes
• POST /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/request-changes - See Participant changes
• GET /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments - See Paginated Pull Request Comments changes
• POST /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments - See Pull Request Comment changes
• GET /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments/{comment_id} - See Pull Request Comment changes
• PUT /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments/{comment_id} - See Pull Request Comment changes

Repositories endpoints

• GET /2.0/repositories/{workspace}/{repo_slug}/watchers - 200 response now has type Paginated Accounts. Previously, this was erroneously not set.

Snippets endpoints

• POST /2.0/snippets/{workspace}/{encoded_id}/comments — Changed body parameter schema to Snippet Comment which was previously erroneously set to Snippet. Changed 201 response schema to Snippet Comment which was previously erroneously set to Snippet.
• PUT /2.0/snippets/{workspace}/{encoded_id}/comments/{comment_id} — Added body parameter schema to Snippet Comment which was previously erroneously unset. Changed 200 response schema to Snippet Comment which was previously erroneously unset.
• DELETE /2.0/snippets/{workspace}/{encoded_id}/watch - Unset 204 response schema, which was previously erroneously set to Paginated Users.
• GET /2.0/snippets/{workspace}/{encoded_id}/watch - Unset 204 response schema, which was previously erroneously set to Paginated Users.
• PUT /2.0/snippets/{workspace}/{encoded_id}/watch - Unset 204 response schema, which was previously erroneously set to Paginated Users.
• GET /2.0/snippets/{workspace}/{encoded_id}/watchers — Changed 200 response schema to Paginated Accounts schema, instead of Paginated Users schema.

Users endpoints

• GET /2.0/user — Changed 200 response schema type to Account, instead of User.
• GET /2.0/users/{selected_user} — Changed 200 response schema type to Account, instead of User.