I was conducting an accounting of my API design toolbox, and realized it hasn’t changed much lately. It is still a very manual suite of tooling, and sometimes services, that help me craft my APIs. There are some areas I am actively investing in when it comes to API design, but honestly there really isn’t that much new out there to use. To help me remember how we got here, I wanted to take a quick walk through the history of API design, and check in on what is currently available when it comes to investing in your API design process.
API design has historically meant REST. Many folks still see it this way. While there has been plenty of books and articles on API design for over a decade, I attribute the birth of API design to Jakub and Z at Apiary (https://apiary.io). I believe they first cracked open the seed of API design, and the concept API design first. Which is one of the reasons I was so distraught when Oracle bought them. But we won’t go there. The scars run deep, and where has it got us? Hmm? Hmm?? Anyways, they set into motion an API design renaissance which has brought us a lot of interesting thinking on API design, a handful of tooling and services, some expansion on what API design means, but ultimately not a significant amount of movement overall.
Take a look at what AP+I Design (https://www.apidesign.com/) and API Plus (https://apiplus.com/) have done to architecture, API has done for the oil and gas industry (https://www.api.org/), and API4Design has done for the packaging industry (http://api4design.com/)—I am kidding. Don’t get me wrong, good things have happened. I am just saying we can do more. The brightest spot that represents the future for me is over at:
- Stoplight.io - They are not just moving forward API design, they are also investing in the full API lifecycle, including governance. I rarely plug startups, unless they are doing meaningful things, and Stoplight.io is.
After Stoplight.io, I’d say some of the open source tooling that still exists, and has been developed over the last five years, gives me the most hope that I will be able to efficiently design APIs at scale across teams:
- Swagger Editor - I still find myself using this tool for most of my quick API design work.
- API Stylebook - What Arnaud has done reflects what should be standard across all industries.
- OpenAPI GUI - A very useful and progressive OpenAPI GUI editor.
- Apicurio - Another useful GUI OpenAPI editor which shouldn’t be abandoned (cough cough).
- Web Concepts - The building blocks of every API design effort is located here.
I use these tools in my daily work, and think they reflect what I like to see when it comes to API design tooling investment. I would be neglectful if I didn’t give a shout out to a handful of companies doing good work in this area:
- Postman - While not coming from a pure API design vantage point, you can do some serious design work within Postman.
- APIMATIC - It takes good API design to deliver usable SDKs, and APIMATIC provides a nice set of design tooling for their services.
- Reprezen - They have invested heavily in their overall API design workflow and are a key player in the OpenAPI conversation.
- Restlet - My friends over at Restlet are still up to good things even thought they are part of Talend.
While I am not quite ready to showcase and highlight these companies because they don’t always reflect the positive API community influence I’d like to see, I don’t want to leave them out for what they bring to the table:
- SwaggerHub - They are doing interesting things, even if I’m still bummed over the whole Swagger -> OpenAPI bullshit, which I will never forget!
- Mulesoft - Their AnyPoint Designer is worth noting in this discussion. I will leave it there.
While writing this, and taking a fresh look at the search results for API design, editors, and tooling, and looking through my archives, I came across a couple players I have never seen before, either because I haven’t been tuned in, or because they are new:
- OpenAPI Designer - An interesting new player to the OpenAPI editor game.
- Visual Paradigm - Another interesting approach to delivering APIs – we may have to test drive.
I do not want to stop there. Maybe there are other API design toolbox forces at play, influencing, shifting, or directing the API design conversation in other ways, using different protocols and approaches:
- GraphQL - Maybe the GraphQL believers are right? Maybe it is the true solution to designing our APIs? What if? OMG
- Kafka - I think an event-driven approach has shifted the conversation for many, moving classic API design into the background.
- gRPC - Maybe we are moving towards a more HTTP/2 RPC way of delivering APIs and API design is becoming irrelevant.
It is possible that these solutions are siphoning off the conversation in new directions. Maybe the lack of investment is due to other influences that go well beyond the technology, or a specific approach to defining and designing the API problems. What might be some out of the box reasons the API design conversation hasn’t moved forward:
- Investment - Most of the movement I’ve seen has occurred as well as stagnated because of the direction of venture capital.
- Hard - Maybe it is because it is hard, and nobody wants to do it, making it something that is difficult too monetize.
- Expertise - We need more training and the development of API design expertise to help lead the way, and show us how it is done.
- Bullshit - Maybe API design is bullshit, and we are delusional to think anything will ever become of API design in the first place.
- My Vision - Maybe my vision of API design tooling and services is too high of a bar, or unrealistic in some way.
Ultimately, I think API design is difficult. I think we need more investment in small open source API design tooling that do one thing well. I think other API paradigms will continue to distract us, but also potentially enrich us. I think my vision of API design is obtainable, but out of view of the current investment crowd. I think API design vision is either technical, or it is business. There is very little in between. This is why I highlight Stoplight.io. I feel they are critically thinking about not just API design, but also the rest of the lifecycle. I’d throw Postman into this mix, but they are more API lifecycle than pure design, but I do think they reflect more of the type of services and tooling I’d like to see.
I do not think resource centered web API design is going anywhere. From what I”m seeing, it is going mainstream. It is simple. Low cost. It gets the job done with minimal investment. I think we should invest more into open source API design solutions. I think we need continued investment in API design services like Stoplight.io, Postman, Reprezen, Restlet, and others. I think we need to shift the conversation to also include GraphQL, Kafka, and gRPC. I think investors can do a better job, but I”m not going to hold my breathe there. In the end, I go back to my hand-crafted, artisanal, API design workbench out back where I have cobbled together a few open source tools, on top of a Git foundation. Honestly, it is all I can afford, but I’ll keep playing with other tools I have access to, to see if something will shift my approach.
