If you want to live and breathe an API first paradigm, you have to cater for the journey experience not only for the receiving end. Referring to users who benefit from well integrated products and services in many ways.
But as well the the force that can turn machine to machine communication into added value: developers and their onboarding experience.
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. Your API will be a soul-less, abandoned API horror house.
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 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.