Imagine its's the year 3000 (😂) and API version 1.0 is out. How would you like it to be?
As I recently mentioned in a comment on DEV, designing APIs is hard, don't believe anyone that will tell you it's easy :-D
An API has many stakeholders, here some of them and some of the questions I started asking myself when I started thinking about API v1:
those who host and serve content of the platform: How resource intensive is the API? Does its performance holds by scaling traffic? How costly it is? Will all Forems support the same version of the API at the same time? What happens to performance if a small Forem suddenly gets a very popular integration that uses its API? How do we keep track of usage of all API endpoints on all Forems?
the machines (not just the end HTTP client a developer writes, but the internet is full proxies, caching servers and others): Is it discoverable? Is a public schema available? What's the deprecation policy? Will the software automatically know if something is deprecated? Can a piece of software navigate it without human input?
the developers: Is it documented? Is there a developer community around this API? Is the content available to all or needs authentication? What type of authentication? Why just one type? Is the client code autogenerated by the specification? Do I have to provide personal identifiable information to get access to this API? Is it security audited? Is a SLA available? How does versioning work? How forward thinking the API is?
the system integrators: *How do I make "my" users interact with that API without them being users of that Forem? Is access centralized or decentralized? How do I get support?
The API world is full of opinions and full of many, many, keywords: resources, API evolution, HTTP, RESTish, REST, GraphQL, JSON schema, OpenAPI, SOAP, RPC, authentication, authorization, webhooks, web sockets, Cap’n Proto, Protocol Buffers, binary formats, pub/sub, streaming and many, many more.
We'd like to understand how you'd envision a future API to work, not just in the sense of formats and protocols.
What does this API should enable you to build? What does the API should enable people to build, for non technical users in other Forems?
I have hints of ideas (totally not fully formed) for the year-4000-maybe-API-v2 as well: should the API allow cross Forem requests? Let's say you're authenticated on Forems A, B and D. Should, with some discoverability and auth wizardry, an API call on Forem A be able to retrieve your content on B and D? How?