Issue Summary

• As per our new SOP, I am raising this as a public bug to gain traction on the existing ADOC ticket

EXISTING BCLOUD-20744

• Please improve Bitbucket API documentation and provide example of the POST JSON body for creating deployment environment within a repository using Bitbucket open API: 
  https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Bworkspace%7D/%7Brepo_slug%7D/environments/#post

• Specify that we only support the "name" for already existing environments and highlight it as a requirement. 
• When user is trying to create a deployment environment with the name that doesn't already exist we respond with: 

  {"key": "deploy-service.request.validation-error","message": "The request body contains invalid properties","arguments": {"environment.environment_type.name": "Unknown environment type."}
  

  Here is the example of the POST request that end users can use for reference, until the public documentation is updated: 

  {"deployment_gate_enabled": false,
  "rank": 0,
  "hidden": false,
  "type": "deployment_environment",
  "slug": "staging123",
  "environment_type": {
  "type": "deployment_environment_type",
  "name": "Staging",
  "rank": 1
  },
  "name": "Staging123"
  }
  OR 
  {
  "hidden": false,
  "type": "deployment_environment",
  "slug": "feature1234-6",
  "environment_type": {
  "type": "deployment_environment_type",
  "name":"Production",
  "rank": 0
  },
  "name": "Feature1234-6"
  }
  

   
  FURTHER INFORMATION

• For updating an environment (for example a namechange), there is also nothing in the API documentation about the JSON payload required - if we could include payload information for example to UPDATE the deployment environment name:

  {
  	"change":
  	{
  		"name":"InsertNameHere"
  	}
  }
  

This is reproducible on Data Center: no

Steps to Reproduce

1. Observe existing API documentation

Expected Results

• API documentation is clear and up-to-date

Actual Results

• API documentation needs to be updated

Workaround

• Currently, we will need to refer customers to this public bug for assistance with JSON payloads