Service Rest Apis and Clients (or lack thereof)

[Anthony Torres]

Problem:

Recently I've been working with Stash's rest API and I have encountered a problem; I assume I am not the only developer who is experiencing this. For any arbitrary Atlassian service and version combination, a client may or may not exist with some number of features, the clients are often hand rolled by third parties which can be buggy, or the client library may not be up to date with the latest API changes. I think you can see where this is going...

I have been working on a personal node project and it lead me to the question, "Is there a Stash Rest Client in npm?" Searching npm I found less than promising results.  These node modules cover some of the basic use cases, but not what I need for my project, so I can fork the project, submit a pull request, hope it gets merged or maintain a fork. But what happens when I need to port my project to Ruby for whatever reason?

Proposal:

I noticed that Stash, in particular, has a very well documented rest api. However, there are no first-party clients that support communicating with the api. I would expect for an api version, a client would be provided in a variety of languages. This sounds like it would produce a significant amount of burden on the developers who are now responsible for producing a service, an a client in a bunch of languages.

There already exists a tool, Swagger, which has a well documented spec and a number of code generators which can produce a client. This would allow Atlassian to provide clients for each of their services that are up-to-date with the latest api versions.

Ask:

Is there a reason why Atlassian is using their own rest spec instead of the Swagger spec? Can Atlassian provide a Swagger spec, either instead of or in addition to their current format? This will reduce the friction for developers to use their rest services.

[evzijst]

The lack of native Swagger support is mostly historical, as most of our products predate Swagger. However, we are currently evaluating Swagger as the de-facto descriptor language for Bitbucket Cloud.

[Anthony Torres]

@Erik van Zijst thanks for the reply, the would be tremendously helpful for our team. I would appreciate any follow up on this tread as we are actively developing something that would greatly benefit from a rest client and I believe Swagger will lower the barrier to getting a node client. Do you know if there is an approximate time frame? Will this be available with the next major release of bitbucket server or is this a far future conversation?

[evzijst]

First of, we're looking at Swagger for Bitbucket Cloud only at this time, not Bitbucket Server. Server might follow Cloud if Swagger is successful, or it might not. We also have no ETA for Swagger in Cloud, but I expect a few months. You can see an early version today at https://api.bitbucket.org/swagger.json with an HTML preview at https://swaggerhtml.useast.atlassian.io/index.html