Talk:Core Platform Team/Initiative/API Gateway/Documentation Plan

Use api.wikimedia.org as the domain for the MVP of the API Portal

I'm strongly in favour of using developer.wikimedia.org, with developer.wikipedia.org as a redirect. (Or, if rebranding happens, we switch the redirects around.)

"developer" is a popular domain name for API portals. developer.apple.com, developer.twitter.com, developer.mozilla.org. Facebook uses developers.facebook.com, and Google uses developers.google.com.

The more we can adapt to developers' expectations for the site, the more we can expect better participation. The domain name we use isn't critical, but it would be great to go out with our best foot forward.

I'm also a strong -1 on dev.wikimedia.org. It's not really good strategically, and it's already in use for auto-generated documentation.

phab:T67074 is an older related idea. It proposes what I believe is a wider scope for the portal than this proposal. It would be nice to find out if the two are actually compatible ideas.

I agree; I think this project can be the kernel of a comprehensive developer portal. How is this for a way forward?

- Deploy API gateway documentation on developer.wikimedia.org

- Link to current documentation and interfaces for other services

- As needed, migrate documentation and interfaces to the developer hub

I think my concern with pushing this work off to the side into some other domain name, and not the developer.w.o one that people expect to see, is that we're then back to a situation without a good portal entry point for developers. Instead of waiting for a future effort on this, why don't we start it now? We're really close.

I could definitely see a portion of the portal as proposed here devoted to linking out to other Wikimedia developer resources, which would help us get closer to the idea proposed in phab:T67074 and would make the developer.wikimedia domain more applicable.

The proposal to use api.wikimedia.org actually makes the most sense to me. Putting the endpoints, the resource provisioning process, and the documentation together under a single URL space just seems more discoverable.

developer.wikimedia.org feels quite broad given all the technology and architecture stacks that we have in the Wikimedia ecosystem. Hence to me it feels misleading if this site was "only" about an API gateway, while developers might be looking for other documentation (random example: https://doc.wikimedia.org/ ).

I think it's only about an API gateway at first.

I think we can start off with links out to the other important entrypoints, and gradually migrate any content we want on this portal.

Every journey starts with a first step. Let's give this effort a chance to become the developer portal we all want to have.

@EProdromou (WMF) I am quite concerned when I read "gradually migrate any content" without being aware of any information what "content we want" means. Do you refer to some or all stuff on doc.wikimedia.org? Some stuff on mediawiki.org (if so, which)? Maybe some stuff on wikitech.wikimedia.org? How does this all fit together in the bigger picture? When to go to which site ideally? (Notorious reference to https://xkcd.com/927/.) Can you please share more information?

In my understanding, if you are not after a spontaneous hitchhiking trip with no time and money constraints, every journey starts with a basic plan (in this case, defining the scope in contrast to existing docs and sites hosting docs, plus allocated resources) before using a name which creates expectations that might not get fulfilled.

Good question, Andre!

My main goal, as Product Manager for APIs, is to have an easy way for developers to get Wikimedia content and data with our public APIs.

So, a single portal that they can use to sign up for an account, get an OAuth key, read tutorial and example code, and then start coding, using API reference documentation as they're writing code.

This goal isn't well-served as part of a standalone site, shunted off to the side. That would make it hard for people to find the functionality I'm trying to share. It works best if it's part of a more integrated portal that is the official place we want all developers for Wikimedia to start.

It feels like we have had this idea of a developer portal multiple times, and that it's generally agreed that it would be good for the Foundation and the movement. I think we can work together to make that happen.

I realise that's not a detailed description of what content would go onto a developer portal. If I were to start somewhere, I'd start with How to contribute; content that was more than a click or two away from that page might not be what we want new developers to start off with.

I'd say in general doc.wikimedia.org stuff wouldn't make sense to include; that documenting MediaWiki on mediawiki.org makes a lot of sense; and that a lot of the content on mediawiki.org that's not actually about installing, extending, or hacking MediaWiki might make sense to transfer. And I'd put an asterisk on the API documentation for MediaWiki and MW extensions, since they'd be important both for self-hosted MW and for people trying to work with Wikimedia sites.

So, a single portal that they can use to sign up for an account, get an OAuth key, read tutorial and example code, and then start coding, using API reference documentation as they're writing code.

That describes mediawiki.org. :) The OAuth consumer registration got moved from here to meta for hysterical raisins, but it was first done here on mw.o. The rest is already here including very extensive documentation of the Action API and at least stub pages and external links to other APIs and datasets.

It feels like we have had this idea of a developer portal multiple times, and that it's generally agreed that it would be good for the Foundation and the movement. I think we can work together to make that happen.

I agree, but this is also literally the first time you are talking near me about it. When the pitch that became the Core Platform Team was going around, the bullet point about improving documentation was very much about on-boarding new technical staff to Wikimedia Foundation teams. I had some quibbles about wording, but by and large I was fine with this idea on the basis that anything that made it easier to get started working on a Wikimedia Foundation team was pretty likely to translate to making it easier to become a technical contributor regardless of your employment status. A couple of years later I am glad to see active work happening based on that proposal, but not so glad to see that work happening in a silo focused on an API project without much discussion outside of the Foundation team that is sponsoring the work.

I fully understand that Evan and most of the other folks working on this project were not at the Foundation in 2018 when the things I am referencing above were active topics of discussion. I also recognize that this project could be (and should be) a part of a larger work towards the goal of "solving" Bug #1. I am concerned however that there is currently a rush to solve one aspect of a much larger problem in a way that will make more barriers to follow on work rather than fewer. Accumulation of technical debt is already a major problem within our movement; making more when we could at the very least be debt neutral is a concern.

Thanks for your feedback, everyone. Considering the API Portal’s exclusive focus on the API Gateway, I think api.wikimedia.org is the best option for the domain. I’m going to resolve this topic, and we can revisit it in the future if the scope of the API Portal changes.