Feat Swagger V3: Update account schema

[Sander Mol]

The #/components/schemas/account definition no longer matches the reality.

For example, the endpoint of https://api.bitbucket.org/2.0/repositories/<userame>/<repository>/branch-restrictions returns the following users object (account object according to the specs):

"display_name": <string>

"links": <account_links>,

"type": "user",

"uuid": <string>

"account_id": <string>

"nickname": <string>

Which mismatches the definition of https://dac-static.atlassian.com/cloud/bitbucket/swagger.v3.json. I believe the following points would summarize this:

1. remove `username` from the schema
2. add `account_id`, `nickname`, `display_name` and `uuid` to the schema

Let me know if more information is needed.

[Theodora Boudale · Accepted solution]

Hi Sander,

Thank you for reaching out.

The "uuid" is already included in the account schema:

"account": {
        "allOf": [
          {
            "$ref": "#/components/schemas/object"
          },
          {
            "type": "object",
            "title": "Account",
            "description": "An account object.",
            "properties": {
              "links": {
                "$ref": "#/components/schemas/account_links"
              },
              "created_on": {
                "type": "string",
                "format": "date-time"
              },
              "display_name": {
                "type": "string"
              },
              "username": {
                "type": "string",
                "pattern": "^[a-zA-Z0-9_\\-]+$"
              },
              "uuid": {
                "type": "string"
              }
            },
            "additionalProperties": true
          }
        ]
      }

Please allow me some time to reach out to the development team regarding the rest and I will get back to you on this.

Kind regards,
Theodora

[Theodora Boudale]

Hi Sander,

I discussed your feedback with the development team.

remove `username` from the schema

The `username` is still returned in https://api.bitbucket.org/2.0/user for the currently logged-in user, but it won't be returned for other users, so yes, it's correct if we remove this. There is an internal ticket for the dev team to remove that property.

add `account_id`, `nickname`, `display_name` and `uuid` to the schema

We have a hierarchy of accounts. There are three distinct subclasses of account, they are user (a human user account), app_user (a system / bot user account), and team (which represents a workspace).

{
"account": {
"allOf": [
{
"$ref": "#/components/schemas/object"
},
{
"type": "object",
"title": "Account",
"description": "An account object.",
"properties": {
"links": {
"$ref": "#/components/schemas/account_links"
},
"created_on": {
"type": "string",
"format": "date-time"
},
"display_name": {
"type": "string"
},
"username": {
"type": "string",
"pattern": "^[a-zA-Z0-9_\\-]+$"
},
"uuid": {
"type": "string"
}
},
"additionalProperties": true
}
]
},
"team": {
"allOf": [
{
"$ref": "#/components/schemas/account"
},
{
"type": "object",
"title": "Team",
"description": "A team object.",
"properties": {
"links": {
"$ref": "#/components/schemas/team_links"
}
},
"additionalProperties": true
}
]
},
"app_user": {
"allOf": [
{
"$ref": "#/components/schemas/account"
},
{
"type": "object",
"title": "App User",
"description": "An app user object.",
"properties": {
"account_id": {
"type": "string",
"description": "The user's Atlassian account ID."
},
"account_status": {
"type": "string",
"description": "The status of the account. Currently the only possible value is \"active\", but more values may be added in the future."
},
"kind": {
"type": "string",
"description": "The kind of App User."
}
},
"additionalProperties": true
}
]
},
"user": {
"allOf": [
{
"$ref": "#/components/schemas/account"
},
{
"type": "object",
"title": "User",
"description": "A user object.",
"properties": {
"links": {
"$ref": "#/components/schemas/user_links"
},
"account_id": {
"type": "string",
"description": "The user's Atlassian account ID."
},
"account_status": {
"type": "string",
"description": "The status of the account. Currently the only possible value is \"active\", but more values may be added in the future."
},
"has_2fa_enabled": {
"type": "boolean"
},
"nickname": {
"type": "string",
"description": "Account name defined by the owner. Should be used instead of the \"username\" field. Note that \"nickname\" cannot be used in place of \"username\" in URLs and queries, as \"nickname\" is not guaranteed to be unique."
},
"is_staff": {
"type": "boolean"
},
"website": {
"type": "string"
}
},
"additionalProperties": true
}
]
}
}

The base type of all these is the account type. Almost all of our APIs swaggers are defined as returning an account object, which means that any of the 3 subclasses of account can be returned.

So, in the API response, if you notice an account object with the type field of the user, you can then expect that object to have all the required properties of both the account and user.

`account_id` and `nickname` are part of the user object while `uuid` and `display_name` are part of the account object. 

Please feel free to reach out if you have any questions.

Kind regards,
Theodora

[Theodora Boudale]

Hi Sander,

We have updated our swagger and the `username` is now removed from the account.

I also edited my previous reply to reflect that `display_name` is already part of the account. I missed that, I apologize if I caused any confusion with this.

Kind regards,
Theodora

[Sander Mol]

Amazing, thank you very much for the detailed response @Theodora Boudale! I just noticed the removal of `username`, thanks for the quick response.

I see the base-type of account and was not aware of this structure, so thank you.

[Theodora Boudale]

You are very welcome, Sander. Please feel free to reach out if you ever need anything else!