1. Bitbucket
  2. Public Issue Tracker
  3. master
  4. Issues


Issue #4524 closed

REST API Making the Bitbucket RES API more RESTful (BB-50)

Blake Willard
created an issue

I just recently started to use your service (aside: I'm in love) and attempted to add some bitbucket cli functionality into my dev environment by utilizing the REST API. Below are several different ideas that may make programming against the API even easier while also moving it towards a more pure RESTful interface.

==== Uniform Interface ==== Currently Deployment Keys, Likes, Repository Links, according to the documentation (https://confluence.atlassian.com/display/BITBUCKET/Using+the+bitbucket+REST+APIs), are all using what I assume is an older uri (i.e. https://bitbucket.org/!api/1.0/repositories/bitbucket/) whereas all other resources are accessible via the more comprehensible https://api.bitbucket.org/1.0/. I chalked this difference up to the API's experimental nature but felt it deserved a mention. I think it is implicit how a uniform entry to the API lends it self to ease/quality of programmability.

==== No Client State Tracking Yields Robustness ==== Terrible title I know but regardless, much of the inspiration for this was taken from salesforce.com's implementation of REST (http://www.salesforce.com/us/developer/docs/api_rest/).

I shouldn't have to code into the client the various uris that the API provides to me. This would break my application on every API change. Not only that, but I have no way on the client side of probing the interface for exposed resources. For example:

curl https://api.bitbucket.org/1.0 { "changesets":"/[uri]", "deployment_keys":"/[uri]" ... } This way I can build the client around what is actually there not what the documentation said when I first started development. It's easy to see how the client can react gracefully to api changes if the keys ('changeset' and 'deployment_keys' in the above example) remain constant throughout a version.

I believe what's being done currenty with the repositories resource is exemplary and should be the model for all other resources.

Comments (4)

  1. Dylan Etkin

    Thanks for reporting.

    We are aware the existing API is inconsistent and a bit lacking.

    We have been focusing on making sure that most operations are available in the API and that the new endpoints are consistent.

    However at some point we certainly plan on creating a v2 REST API. I will be honest, I don't see that coming this year. I do hope that sometime next year we will be able to tackle the new API.



  2. Log in to comment