Ahoy, fellow developers! We’re excited to tell you about Tugboat’s latest development effort: our new REST API!


As a tool created by developers for developers, Tugboat’s development focus since early on has been “how can we better support developers and their organizations?” One way we’ve driven that focus is by asking existing and potential partner organizations what would make Tugboat a better tool for them. One potential partner wanted to see a REST API to enable ease of integrating Tugboat into their backend.

While Tugboat has had an API of sorts, it was primarily for internal use and hadn’t been conceived and documented for Tugboat users to call. Developing a fully-documented REST API, following standards that developers would already be familiar with, seemed like a good way to facilitate new developers onboarding and integrating Tugboat with their webapps. With the ask being such a clear win for existing and potential partners alike, Tugboat’s development resources focused on creating our new REST API.

Updating underlying infrastructure to prepare for REST API

With the decision made to develop a REST API, Tugboat’s principal developer began an audit of Tugboat’s existing infrastructure. The first question was: what sort of changes needed to be made to Tugboat’s underlying infrastructure to prepare for the REST API? With an existing websocket API in place, the first task was to examine that internal API and determine whether its calls would be compatible with a REST API. What were the existing endpoints for the current iteration of the API, and would a REST API even make sense with the way Tugboat’s infrastructure was constructed?

Fortunately for our developers, the legacy code didn’t contain a lot of cruft that would need to be worked around to implement a REST API. After some documentation-driven development of the new REST API, we determined that the infrastructure changes we wanted to implement would make Tugboat easier to load-balance internally, and would support more capacity; both good for the app, regardless of the REST API. With infrastructure decisions made, implementing them was relatively straightforward, and we had what we needed to support the new REST API.

Documentation-driven development

During the infrastructure audit, Tugboat’s developers began the process of documenting the new REST API, before a single line of code was ever written. The first step was simply listing all of the endpoints, and any necessary notes about those endpoints. Using OpenAPI for the documentation resulted in a massive YAML file of endpoints that quickly became unwieldy. Our principal developer made a spreadsheet of all of the required endpoints and notes, and only added them to the documentation as they were implemented. This had the added benefit of ensuring that the documentation was always in-step with the API as it currently existed; future endpoints that had not yet been coded were listed in the spreadsheet, but not in the documentation.

During the course of documenting the ideal version of our REST API, our developers were able to test a few different mental paradigms without actually spending the development resources implementing, and then changing, code. For example, early in the development process, we tried borrowing a few paradigms from the JSON API, which quickly turned out to be far more complex than desired when applied to Tugboat’s functionality. By documenting the API thoroughly before implementing it, we got a clear road map of any remaining infrastructure changes we’d need to make to support the API, and had an opportunity to mentally test different directions for our API before putting any of them in code. The documentation skeleton then became the guide for implementing the API.

Armed with a plan, our developers began working on turning that documentation into reality, and moved forward with implementing the new API in code.

MVP launch, continuing development

With much of the underlying development now complete, we’re excited to announce that Tugboat’s new REST API has been launched! Most of the API’s functionality is in place; we’re still working on development of a few more features, mostly around event handling and firing webhooks. We’ll also be beefing up some of the headers to make more of the endpoints automatically discoverable. Check out our REST API documentation - you can view it on our site, or download it as an OpenAPI specification for use with your favorite tools.

If you do end up using our new REST API, or have any questions about it, shout out to us on our Tugboat Support Slack, or shoot us an email at Tugboat support. We’d love to hear how you’re using it; some of you Tugboat Captains have come up with some really creative ways of leveraging Tugboat for your development needs! And as always, we continue to strive to make Tugboat the best tool it can be for you and your organization, so let us know if there are any features you’re dying to see - they just might make it onto our roadmap!