Publishing our OpenAPI Spec and Documentation

More than just a milestone

Sometimes life at Upvest seems like one long stream of milestones and reasons to celebrate. If you follow our social media you’ve probably grown used to a fairly continuous stream of exciting news and developments - last year was a huge year for us.

In 2022 we:

.. and that’s just the tip of the iceberg!

Yet, amongst all of these reasons to celebrate, the way we’ve kicked of 2023 is really close to my heart. On Monday, 23rd of January, shortly after 10am, we announced the publication, to the world at large, of our OpenAPI specification and supporting documentation.

From now on the world can see clearly what our API does, and our documentation is open to public scrutiny. Things will never be quite the same again!

This will be the first of two blog posts in which I’ll explain a little about the journey that brought us to this point. In this post, I’ll talk a little about the commercial decision to publish these materials, and the rationale behind it all. In the second post I’ll explore Upvest’s approach to managing the specification and documentation and introduce the technology that supports us.

Making the decision to expose our API to public scrutiny

The decision to publish the Open API specification and documentation has been sitting in my mental intray since the day I accepted Upvest’s job offer, nearly a year ago. Much work had already been done at that point. Upvest’s excellent product and engineering teams had already built the backbone of the investment API, with an OpenAPI spec and an admirable set of guides, you could see huge value in what was there already, and our early clients have been building on that value. So why wait so long to share what we’ve done with everyone else?

API Portal Screenshot

For many API vendors, the decision to share details of that API with the world is a “no brainer”. If you’re allowing people to consume your API for free, or access is only a simple credit-card transaction away, then it makes absolute sense to have as much information out in public as possible. After all, why create barriers that might make it harder for people to choose to use your API, or create extra headaches by managing secure access to the information when you don’t need to? Your API can’t be a closely guarded secret if it’s so easy to access. Arguably, easy transparent access to APIs is the most important part of the revolution they’ve bought to the modern technology landscape. Any active software developer can probably point to a favourite API able to consume transparently that made their life better.

So it’s clear that we recognise the value of openness, but our business is a little more complicated. We’re operating in a highly regulated industry and marketing to a specialised group of potential clients in the finance sector. We have to ensure that every aspect of our customer relationship is being handled correctly and that we’re a trusted, reliable partner. We’re also a startup, being careful about how we scale, even if it were possible to make the API available to anyone with a credit card, that wouldn’t be the best and most sustainable way for us to grow. We’re trying to build something, new and different to other companies in our space, and in doing so we’ve already gained quite a lot of attention in our marketplace, without the need to publish the API to the world at large.

One might worry that being so open will make it easy to follow in our footsteps, or create complexity and noise that will detract from other goals. Yet, the message from Upvest’s leadership has always been clear, and my own view falls in line with that. Being out in the open is something we wanted.

Why do we want this information publicly available?

Firstly, it puts a lot more information into the hands of people trying to see if Upvest is a viable option for their project. You can see what we do and understand our utility. We hope it is clear that we’re not just talking about a revolutionary investment API - we’re living that dream. This is the first step in our efforts to make it easy to understand, investigate and develop against API without needing to take the steps required to gain access to the live API. The Developer Experience tribe has a wealth of ideas here, so watch this space!

Of course, the second point is that all of the above also applies to people considering applying for a job at Upvest. Now you can get a much better feel for what we’ve done so far, and how we’ve gone about it.

API Portal Screenshot

Thirdly, placing our Open API Spec and documentation in the daylight allows us to gather feedback from a wider audience. Throughout our portal, you can provide a “Thumbs Up” or “Thumbs Down” on any page, and leave a text comment that we’ll see in the management tools. We’re excited to see what people think and we have a commitment to continuous improvement of our documentation and tools. We encourage you to get in touch!

Finally, and perhaps most importantly, Upvest is an ambitious company. We don’t want to be just another vendor, we want to carve out a new space and define what that looks like. To do that we have to use the experience we have and confidently assert the “shape” of our API. Anyone trying to copy our API would only confirm that we’ve done that part right. To win in such a market you have to do more than this. You need to deliver better than your competitors: faster times to market and better developer experience without sacrificing reliability, performance or compliance. We’re not naĭve about competition, facing it square on and pushing forward confidently are the way we roll :-D

The remaining question is then…

Why now?

Given all of the above, why was this week the time to publish documentation and OpenAPI spec?

Is it because we think we’ve polished everything as far as we can? There’s a clear answer here: “No”. There’s a lot of work still to do, I don’t envisage there ever being a day when we’re “done”. That’s important to recognise, Upvengers like to talk about “Progress over perfection”. We iterate and move towards our goals continuously. The question of when to go live came down to the following factors:

  • We’ve developed enough functionality to be a genuinely useful solution.
  • We’ve road tested our API and documentation with initial customers.
  • We’ve established good development practices around our API spec and documentation.
  • We’ve got tooling in place to support those practices and give us the flexibility we require (more on that in my next post!).
  • We’ve got a Developer Experience Engineering team in place who are capable of coping with ongoing development of this information, in public.

We actually achieved most of these goals in Q3 and Q4 of 2022, so all that was required was an early-year push to go public and finally we made it!

We’re so glad to share our work with you all and, a few days in, we’re already seeing positive outcomes from it.

Fizzy drinks all around!