Opened T330634 to the API platform folks to grant us access to the API gateway portal.

I've added the Lift Wing team to the documentation editors group, so you're ready to start adding docs. I've created a landing page and an endpoint page to help you get started. (Feel free to rename these pages if you'd prefer other titles.) Let me know if you have any questions!

@apaskulin thanks a lot!

Change 898695 had a related patch set uploaded (by Elukey; author: Elukey):

[operations/deployment-charts@master] services: set custom rate limits for Lift Wing on the API Gateway

https://gerrit.wikimedia.org/r/898695

Change 898695 merged by Elukey:

[operations/deployment-charts@master] services: set custom rate limits for Lift Wing on the API Gateway

https://gerrit.wikimedia.org/r/898695

Since it was asked over IRC: Lift Wing documentation can be found in https://wikitech.wikimedia.org/wiki/Machine_Learning/LiftWing#Usage, this task is to copy the same information to the API portal :)

Added docs pages!! To avoid mixing up and complicating them, I decided to:

• Have a dedicated page for each revscoring model, even if they share a lot.
• Have a dedicated page for the Article Topic Outlink model (different from the above ones).

List of pages that I created:

https://api.wikimedia.org/wiki/API_reference (see Lift Wing section)

https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing

https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Get_revscoring_goodfaith_prediction
https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Get_revscoring_damaging_prediction
https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Get_revscoring_reverted_prediction
https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Get_revscoring_drattopic_prediction
https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Get_revscoring_draftquality_prediction
https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Get_revscoring_articlequality_prediction
https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Get_revscoring_articletopic_prediction

https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Get_articletopic_outlink_prediction

I also tried to add schemas related to the objects returned in the HTTP responses:

• articletopic outlink:
  • https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Article_Topic_Outlink_score_object
  • https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Article_Topic_Outlink_scores_object

• revscoring (a single one common to all models)
  • https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Revscoring_Score_object

@apaskulin Hi! When/if you have a moment could you let me know if the above work makes some sense? It is definitely a starting point, not the final version, but some early feedback would be appreciated!

🎉 Nice work! I fixed up the navigation so the pages appear correctly in the sidebar. (For pages to appear in the sidebar, the DEFAULTSORT number on each page must be in sequence, without duplicates.) I also made a few small fixes, most notably moving API_reference/Service/Lift_Wing/Get_revscoring_drattopic_prediction to API_reference/Service/Lift_Wing/Get_revscoring_drafttopic_prediction to fix a typo. (I opted not to leave behind a redirect since these pages are so new.) I also added Lift Wing to the changelog to make it official.

Here's some early feedback:

• I had expected that you'd document these as a single endpoint, but considering the differences in request parameters, I think you made a good decision here to document them separately.
• Unless there's an endpoint that returns the Article Topic Outlink score object by itself, I think we could delete that page and move the information to Article Topic Outlink scores object page.
• To help complete the schema tables with the correct types and required/optional tags, I created a page showing the different templates that are available. This isn't a perfectly optimized system, but hopefully this page gives you a good picture of what's available.
• Eventually we can reduce duplication by moving some content into transcluded pages. For example, the POST Parameters section is shared between a few endpoints. But this more of an optimization for maintainability that we can look into once the docs are more stable.
• In the long term, we'll want to try to remove as much jargon as we can from these docs. "Lift Wing", "revscoring", "outlink", even "Kubernetes" can be hard terms to understand for end users of these docs. The team may already be considering this, but I wanted to note here that we should start thinking about how to describe the functionality of these endpoints in plain language (or as close as we can get).

I'm excited to see this coming together! Let me know if you have any questions.

In T325759#8711938, @apaskulin wrote:

🎉 Nice work! I fixed up the navigation so the pages appear correctly in the sidebar. (For pages to appear in the sidebar, the DEFAULTSORT number on each page must be in sequence, without duplicates.) I also made a few small fixes, most notably moving API_reference/Service/Lift_Wing/Get_revscoring_drattopic_prediction to API_reference/Service/Lift_Wing/Get_revscoring_drafttopic_prediction to fix a typo. (I opted not to leave behind a redirect since these pages are so new.) I also added Lift Wing to the changelog to make it official.

Thanks! Didn't spot the typo sorry :(

Here's some early feedback:

• I had expected that you'd document these as a single endpoint, but considering the differences in request parameters, I think you made a good decision here to document them separately.

I had the same initial idea, but then when I tried to implement it the overall result was too complicated, so I preferred to keep it simple (even if a little more repetitive),

• Unless there's an endpoint that returns the Article Topic Outlink score object by itself, I think we could delete that page and move the information to Article Topic Outlink scores object page.

Correct we should return only the "scores" object!

• To help complete the schema tables with the correct types and required/optional tags, I created a page showing the different templates that are available. This isn't a perfectly optimized system, but hopefully this page gives you a good picture of what's available.

The page is really great, it will definitely help people (I struggled a bit in finding the right tags etc..)

• Eventually we can reduce duplication by moving some content into transcluded pages. For example, the POST Parameters section is shared between a few endpoints. But this more of an optimization for maintainability that we can look into once the docs are more stable.

+1

• In the long term, we'll want to try to remove as much jargon as we can from these docs. "Lift Wing", "revscoring", "outlink", even "Kubernetes" can be hard terms to understand for end users of these docs. The team may already be considering this, but I wanted to note here that we should start thinking about how to describe the functionality of these endpoints in plain language (or as close as we can get).

Definitely yes, I wanted to add some links as well to those special words, but I failed to do so. For example, revscoring could point to https://github.com/wikimedia/revscoring, and outlink could point to its description on wikitech. Is there a way to do it? Would it be ok? I fear that some technical terms are very specific, for example people may need to know what model they are querying etc..

I'm excited to see this coming together! Let me know if you have any questions.

So far it is has been a great experience, thanks a lot for the support!

@elukey Do you think it’s a good idea to use a nested table as shown below in the Article Topic Outlink scores object?

I have made some changes to the schemas related to the objects returned in the HTTP responses:

1. moved the information in the Article Topic Outlink score object to the Article Topic Outlink scores object. This allows us to delete the former one.
2. updated the other two cases (string/array) in the prediction field for the Revscoring Score object.

Let me know what you think about them!

For example, revscoring could point to https://github.com/wikimedia/revscoring, and outlink could point to its description on wikitech. Is there a way to do it? Would it be ok? I fear that some technical terms are very specific, for example people may need to know what model they are querying etc..

@elukey, this is definitely the right idea. What do you think about linking to https://meta.wikimedia.org/wiki/Machine_learning_models/Production/Language_agnostic_link-based_article_topic_model_card for the outlink endpoint and to https://www.mediawiki.org/wiki/ORES for the others? I think both of these are great resources that will help users understand the data they're getting from the API. I've also grouped the endpoints on the Lift Wing landing page to make it easier to choose between them. Let me know what you think!

@achou, the nested table looks great! I've gone ahead and deleted https://api.wikimedia.org/wiki/API_reference/Service/Lift_Wing/Article_Topic_Outlink_score_object.

In T325759#8725364, @apaskulin wrote:

For example, revscoring could point to https://github.com/wikimedia/revscoring, and outlink could point to its description on wikitech. Is there a way to do it? Would it be ok? I fear that some technical terms are very specific, for example people may need to know what model they are querying etc..

@elukey, this is definitely the right idea. What do you think about linking to https://meta.wikimedia.org/wiki/Machine_learning_models/Production/Language_agnostic_link-based_article_topic_model_card for the outlink endpoint and to https://www.mediawiki.org/wiki/ORES for the others? I think both of these are great resources that will help users understand the data they're getting from the API. I've also grouped the endpoints on the Lift Wing landing page to make it easier to choose between them. Let me know what you think!

I like the layout, really nice! Also +1 for the links, it is a good starting point. I added them, lemme know if they look ok or if anything is missing :)

@apaskulin do you think that we are good for the initial version of the documentation, or should we add more?

@elukey, I added a section for the custom rate limits applied in this patch. Feel free to correct it if I interpreted the patch incorrectly.

Other than that, I think the docs looks good! We can continue to make small improvements on the wiki, and I'd eventually love to see some tutorials and beginner-friendly content. But for now, I think we can call this done. Great work! 🎉

In T325759#8739389, @apaskulin wrote:

@elukey, I added a section for the custom rate limits applied in this patch. Feel free to correct it if I interpreted the patch incorrectly.

100% correct thanks!

Other than that, I think the docs looks good! We can continue to make small improvements on the wiki, and I'd eventually love to see some tutorials and beginner-friendly content. But for now, I think we can call this done. Great work! 🎉

Definitely, we are going to add them in Wikitech for the moment (in https://wikitech.wikimedia.org/wiki/Machine_Learning/LiftWing), and maybe we can reference them in the API portal when they are good enough? What do you think? To avoid duplicating too much the efforts (since we'll have internal-WMF users and external-APIGateway ones).

we are going to add them in Wikitech for the moment (in https://wikitech.wikimedia.org/wiki/Machine_Learning/LiftWing), and maybe we can reference them in the API portal when they are good enough? What do you think? To avoid duplicating too much the efforts (since we'll have internal-WMF users and external-APIGateway ones).

Sounds good!

Hi @elukey and @achou! Just wanted to let you know that I moved some things around in the API Portal. You can now access the Lift Wing docs through the API catalog. There is a main Lift Wing API page, and the original landing page is now at Lift Wing API/Reference. There are redirects set up for the old links, so everything should still work. Feel free to reach out if you have any questions or run into any issues.