Add request examples to REST API documentation

The /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/browse/{path:.*} documentation should have examples of requests for creating and editing files.

Not having such examples causes friction between customers and support engineers, as they need to contact us and ask for examples and we, in our turn, need to escalate tickets to Developer Review or ask in chat rooms for examples.

How to create a file:

• Sample request:

  $ curl -u <YOUR_USERNAME> -p -X PUT http://<BITBUCKET_BASE_URL>/rest/api/latest/users/<YOUR_USERNAME>/repos/<REPOSITORY_SLUG>/browse/file.txt -F branch=master -F "message=Create a new file via REST" -F "content=Hello, World!"
  

  Typically one can use something like -F content=@path-to-local-file instead of a simple string like in the example above, so that curl would upload a file.

• The user will be prompted for his Bitbucket Server user password:

  Enter host password for user '<YOUR_USERNAME>':
  

• Sample response:

  {"id":"71b61102887441d215d6aff1a55cd3fff84e6782","displayId":"71b61102887","author":{"name":"<YOUR_USERNAME>","emailAddress":"<YOUR_USERNAME>@example.com","id":7,"displayName":"<Your Username>","active":true,"slug":"<YOUR_USERNAME>","type":"NORMAL","links":{"self":[{"href":"http://<BITBUCKET_BASE_URL>/users/<YOUR_USERNAME>"}]}},"authorTimestamp":1492551512000,"committer":{"name":"<YOUR_USERNAME>","emailAddress":"<YOUR_USERNAME>@example.com","id":7,"displayName":"<Your Username>","active":true,"slug":"<YOUR_USERNAME>","type":"NORMAL","links":{"self":[{"href":"http://<BITBUCKET_BASE_URL>/users/<YOUR_USERNAME>"}]}},"committerTimestamp":1492551512000,"message":"Create a new file via REST","parents":[{"id":"d55ce763387956c3efa691d8f2c2932e1ac5c34b","displayId":"d55ce763387"}]}
  

• Result:
  In the example above, a file named file.txt gets created in the master branch of the repository specified, at http://<BITBUCKET_BASE_URL>/users/<YOUR_USERNAME>/repos/<REPOSITORY_SLUG>/browse/file.txt
  The new commit can be found at http://<BITBUCKET_BASE_URL>/users/<YOUR_USERNAME>/repos/<REPOSITORY_SLUG>/commits

How to edit a file:

• Sample request:

  curl -u <YOUR_USERNAME> -p -X PUT http://<BITBUCKET_BASE_URL>/rest/api/latest/users/<YOUR_USERNAME>/repos/<REPOSITORY_SLUG>/browse/file.txt -F branch=master -F sourceCommitId=71b61102887441d215d6aff1a55cd3fff84e6782 -F "message=Update a file via REST" -F "content=Goodbye, World!"
  

  As a file is being edited, the -F sourceCommitId=last-commit parameter is also needed, as can be seen above. The value to be used for sourceCommitId is the commit ID retrieved from the REST request that created the file, above.

• The user will be prompted for his Bitbucket Server user password:

  Enter host password for user '<YOUR_USERNAME>':
  

• Sample response:

  {"id":"592c372b5ba0c99cebf68eb016f6a341dd684c3d","displayId":"592c372b5ba","author":{"name":"<YOUR_USERNAME>","emailAddress":"<YOUR_USERNAME>@example.com","id":7,"displayName":"<Your Username>","active":true,"slug":"<YOUR_USERNAME>","type":"NORMAL","links":{"self":[{"href":"http://<BITBUCKET_BASE_URL>/users/<YOUR_USERNAME>"}]}},"authorTimestamp":1492551807000,"committer":{"name":"<YOUR_USERNAME>","emailAddress":"<YOUR_USERNAME>@example.com","id":7,"displayName":"<Your Username>","active":true,"slug":"<YOUR_USERNAME>","type":"NORMAL","links":{"self":[{"href":"http://<BITBUCKET_BASE_URL>/users/<YOUR_USERNAME>"}]}},"committerTimestamp":1492551807000,"message":"Update a file via REST","parents":[{"id":"71b61102887441d215d6aff1a55cd3fff84e6782","displayId":"71b61102887"}]}
  

• Result:
  New content is added to the file http://<BITBUCKET_BASE_URL>/rest/api/latest/users/<YOUR_USERNAME>/repos/<REPOSITORY_SLUG>/browse/file.txt.
  A new commit can be seen at http://<BITBUCKET_BASE_URL>/users/<YOUR_USERNAME>/repos/<REPOSITORY_SLUG>/commits