Feat Swagger V3: Update account schema
Asked by 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.


Answers:
author: Theodora Boudale
body: 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

comments: author: Theodora Boudale
body: 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


author: Theodora Boudale
body: 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


author: Sander Mol
body: Amazing, thank you very much for the detailed response [@Theodora Boudale](/t5/user/viewprofilepage/user-id/818086)! 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.


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


Tags: bitbucket-cloud

cloud