How to Promote and Market your API: SPECtacular OpenAPI
This blog is part of our full guide on API Promotion and Marketing strategies. Check it out
If you followed my advice from the previous post on building your API using hype tools, a nice side benefit is all the tooling that comes with popular frameworks. One piece of tooling built into most API development frameworks (ex. Fastify, FastAPI, Zuplo, etc.) is OpenAPI Generation.
What is OpenAPI?#
To put it simply, an OpenAPI spec is a file that lists all the endpoints in your API, describes what they do, documents the different parameters/headers/request bodies, and tells developers what to expect for responses. This file can be created in a few ways:
- Written by hand: very slow process, hard to maintain and keep in sync
- Built through a GUI like Stoplight: faster, but implementation drift is an issue
- Generated through tooling: good at keeping in sync with implementation, but can be inflexible at times. Many frameworks don't allow for much customization, and generation makes the OpenAPI less accessible to your technical writers
What's nice about this spec is that you can plop it into several tools (like Zuplo) to handle many pieces of the API lifecycle.
What Does This Have To Do With API Promotion and Marketing?#
Creating an OpenAPI spec for your API will help you market your API in both direct and indirect ways.
Direct marketing methods with OpenAPI#
- Joining Unified APIs and API Marketplaces is made much simpler via importing your OpenAPI. These are potentially effective distribution channels for selling your API.
- Some API Directories require or strongly encourage you to include a spec to be indexed. Yet another effective method of getting more eyes on your API.
Indirect marketing methods with OpenAPI#
- You can use OpenAPI tooling (ex. Speakeasy, Stainless, Fern, or various OSS)
to generate client libraries / SDKs, allowing you to branch into
different programming language communities more easily. It's much easier to
chat with and onboard Python developers when you can point them to a module
they can
pip installand get started with. Additionally, you can publish these SDKs to package managers like NPM - where downloads will help lend legitimacy to your API - A well-documented API with a great onboarding experience is an API that's easier to market. You can import your OpenAPI file into various documentation tools (ex. Zuplo, Mintlify, Alphadoc, Scalar, or various OSS) and build user-friendly and SEO-optimized API docs. Sometimes, a great developer documentation experience is marketing in itself - how many times have you seen Stripe's API lauded for its high quality documentation?
Is My OpenAPI Spec Good?#
Your OpenAPI spec (and by extension, your API) should be high quality (or should I say, SPEC-tacular? :) ) before you decide to share it with the masses, and the best way to evaluate its quality is by using tools like RateMyOpenAPI. It provides detailed feedback on improving your OpenAPI spec and even improving your API security for free.
Next Steps#
We are done with the steps related to building your API for now. I alluded to a few different ways you can disseminate your OpenAPI spec - and I'll be focusing on API directories next. You can also read our Ultimate Guide to API Promotion and Marketing for a more holistic understanding of the problem.
FAQ#
How should I create my OpenAPI spec?#
This is going to depends on your engineering team setup and resourcing.
For Small teams and Startups I would recommend picking an API framework that automatically generates an OpenAPI spec through your code. Be very careful in which framework you pick as many claim to have OpenAPI support, but in reality only support a few fields. Many recent frameworks are built from the ground up around OpenAPI support. My recommendations are Huma for Go, Tsoa for Typescript, and FastAPI for Python. Your developers will be primarily be responsible for keeping descriptions and summaries up to date, but at least you reduce the risk of having undocumented endpoints or out-of-date documentation.
For Medium to Large teams you might be able to staff a technical writer, who will be in charge of keeping your docs up to date and easy to consume. You will likely want to switch to a mixed approach where the source of truth is your API gateway and its OpenAPI spec. Your services and various APIs can continue to generate OpenAPI specs, but gateways like Zuplo allows you to import your OpenAPI and edit it before making the changes public. This will allow your technical writer to still get the latest changes and updates, but they don't need to go into each API's implementation to document and annotate it.
