@apaskulin asked me to comment on the virtual host name for the API documentation portal.
Our current plan is to use "api.wikimedia.org". This is the same virtual host name as we plan to use for the API Gateway itself.
Other major platforms don't do this; they use another virtual hostname for their portal, and "api" is just for APIs.
My concern is that they know something we don't, and that by launching the portal and gateway on the same virtual domain, we're going to make things harder for ourselves and for api developers.
I'm really reluctant to use api.w.o, the same name that we're using for the API gateway, for the following reasons:
- Part of the value is that the API gateway host **only** has API endpoints. It's conceptually confusing to add a wiki in. We're taking a big step away from having API endpoints be "part of" the wikis by creating this gateway, and sticking a wiki at its root would make that less clear.
- We'll have to take care that there's no overlap between the documentation page namespace and the API urls. I think typically our wikis have everything executable in /w/ and wiki pages in /wiki/, but it's worth examining. And it means we couldn't use any of those as namespaces for APIs.
- We'll need path-based routing, so that some HTTP requests for api.wikimedia.org go to MediaWiki, and others go to Envoy. This has been a source of irritation before, and it would be good to avoid repeating the mistake.
- Cookies. We'll need cookies to maintain the login state on the Portal, but most clients would share those cookies when making API calls, too, since they'd have the same hostname. I think we'd throw them away for API calls (OAuth > Cookies), and there may be a way to limit them to just certain paths on the server, but it's still a bit of a muddle.
There are a lot of other domain names to use; I'd prefer we kept the API Gateway and API Portal on separate virtual hosts.