Since we’re already using the mediawiki-api-announce mailing list in a few places, I’d recommend applying this process more widely and more explicitly as the primary channel for communicating updates to MediaWiki APIs and related APIs. To keep this reply short, I’ve posted my full notes in a wiki page.
Wed, Feb 12
Would this endpoint be affected by the $wgEnableWriteAPI parameter?
Thu, Feb 6
Jan 14 2020
Jan 9 2020
Jan 7 2020
Jan 6 2020
Dec 17 2019
I've reviewed the pages in question and made a series of edits to complete this task. To summarize, I:
Dec 16 2019
Dec 13 2019
Dec 12 2019
Dec 10 2019
To clarify: The Core REST API needs to be documented on mediawiki.org, but it will not be included in the dev portal. The Unified Wikimedia API needs to be documented on the dev portal but not on mediawiki.org. My assumption was that the automated API doc solution would be reusable for both these APIs.
I've updated the task description with the requirements as I see them. Feel free to update as needed!
Dec 9 2019
It seems that the relevant section of Requests_for_comment/Standards_for_external_services has been moved to Wikimedia services guideline. I'd recommend adding the two subsections (Abstractions: A priori versus a posteriori and Pre-generating page-derived data) under Development policies.
Dec 2 2019
Nice find, @Pchelolo! It seems like the docs site for that library is down, but the issue pointed at at this web archive link to view the docs in the meantime. I think using a library like this would meet our requirements, especially if we can find a way to render the spec within MediaWiki.
Nov 26 2019
@nnikkhoui Thanks! That's a good callout. The doc lists the 500 error as a possible response, but I've added a note to the minor type to make that behavior more clear.
Considering that we're moving this endpoint to v0, I'd suggest removing the documentation step from this task in favor of handling the docs in the task that moves this endpoint to v1.
Nov 25 2019
Nov 22 2019
Reviewed synchronously with Evan.
Nov 21 2019
@Clarakosi The draft looks great! The comparison table is set up nicely, and the doc is easy to understand. Nice work!
Nov 20 2019
Updated the wiki page for the REST API and reviewed with Clara.
I've applied review feedback (Thanks, Bill and Nikki!) and removed the Draft banner from the doc.
Nov 19 2019
Nov 15 2019
Nov 14 2019
Nov 13 2019
Nov 12 2019
From a documentation perspective, it makes sense to version the docs by major version. Major versions ensure backwards compatibility and give developers confidence in the API. We'll need to incorporate this into our specifications for the automated API docs.
Sounds good to me! I'll open a patch.
Nov 8 2019
Updated the docs with the minor property.
Interesting results: When I excluded the Code of Conduct page from the Doxygen output, the new pages appeared nested under the Introduction page, which is the outcome I was expecting originally. However, when I added another Markdown file (converting one of the /docs .txt files, for example), the new page appeared nested under that Markdown page. I experimented with creating a dedicated landing page, but it seems that Doxygen randomly selects a Markdown page under which to nest the pages tagged with @ingroup. Since we eventually plan to convert the /docs .txt files to Markdown, I don't think excluding the Code of Conduct is a viable solution here.
Nov 7 2019
Updated the docs with the limit of 1000.
Nov 6 2019
I should have clarified: Looking at the implementation, I'm seeing a limit of 500, which appears to conflict with the task description.
Which standard are we using for language codes? Is there a link to the list of available codes?
Nov 5 2019
I've updated the task description to be more specific and reflect a similar amount of work to the examples listed here.
Updated the docs with a limit of 500 for all history count types.
Nov 4 2019
I've opened a patch for the new exclude pattern, but I wasn't able to find a way to get the class-level Markdown files to not nest under the code of conduct while still having the Markdown formatting render correctly. We'll need to decide whether to revert https://gerrit.wikimedia.org/r/539439 if we can't find a solution for this.
Nov 1 2019
It looks like https://gerrit.wikimedia.org/r/539439 did not completely solve this issue. The new pages now appear nested under the code of conduct page. I'll experiment with how to resolve this, but I'm not sure how this is happening. Additionally, it looks like we'll need another exclude pattern to account for https://doc.wikimedia.org/mediawiki-core/master/php/md_maintenance_benchmarks_README.html
Oct 31 2019
Always happy to discuss this! Here are my notes:
Oct 30 2019
Updated the docs with the new filter names. I didn't include a deprecation notice in the docs because the endpoint is still fairly new, but I can go back and add one if we think it's necessary. In general, I'd like to include an API changelog in the docs, either imported from source or maintained on the wiki.
Oct 29 2019
Updated docs to reflect these changes.
Oct 28 2019
Updated docs to reflect this change
Oct 24 2019
Oct 23 2019
The docs should reflect the current behavior of the endpoint, so we shouldn't change the doc until the functionality is changed.
Oct 22 2019
Do we have a sense of whether we're standardizing on snake case or camel case? For example, the spec for this endpoint has properties in snake case, while the spec for the get media links endpoint has properties in camel case.
Oct 21 2019
Yep! I'll do that later today.
Nice! I was able to get the paragraphs to render correctly by putting @ingroup FileRepo above the title, but, as a result, Doxygen nests the file under the filename in the sidebar:
Oct 18 2019
Hi @Tgr, Thanks for creating this task! Can you elaborate on the documentation needs for "update documentation affected by the new entry point (nice URLs, web server security...)"?
Oct 17 2019
In documenting this endpoint, I've run into a few possible improvements to the user experience.
Updated the documentation with a 403 response for this endpoint. (Compare revisions docs)