If you want to live and breathe an API first paradigm, you have to cater to the end-to-end experience of your clients.
Those clients are of course the people using the final API products - but not only them. The actual, direct clients of APIs are of course DEVELOPERS. Developers who can turn machine to machine communication into added value.
To make it short: Developers are the clients that really need to love your produce. Their onboarding journey has to be fabulous.
To that end, just publishing an API somewhere, somehow is just not good enough. You need to have a marketing plan, some "hmm I might take a second look" bait and an easy, flawless execution. The whole end-to-end "conversion" funnel needs to be in place. Certainly for external developers of your open API, because - they have to have a reason to even spend any time. Yet, that's true as well for your internal developers, within your organization. If the sweetness of your offering isn't obvious, if the execution is questionable, just being within the same organization will not save the day.
In my humble view, for all these reasons, there is no way around a Developer Portal. Which is more than the API endpoints - it includes documentation, maybe videos, very likely pictures (because people are visual!).
Here I have a very simple incarnation of such a Portal that ticks all the basic boxes, even though I am the first to admit the look & feel and documentation overall could be more appealing. Anyway, you'll catch my drift:
- Be clear about what you'll get and what's possible use cases
- Add different product tiers anytime with different rules attached
- Be clear about what a product tier allows you to do and what not
- Allow to easily test-drive the product (=available APIs)
- If you can add a little bit of fun, even better - don't be boring!
Implementation via Azure API Management, however any viable API Management system will do: AWS API Gateway, Google Cloud Endpoints, APIGEE etc.
Exactly like consumers of the output of your CMS do not care about the CMS, developers will/should not care about the underlying technology of your offering.