A little tangential, and maybe it goes without saying, but I really like that MediaWiki API points to documentation in-band when fetched via browser (without the format option). For example:

https://en.wikipedia.org/w/api.php?action=query&prop=pageimages&piprop=thumbnail&pithumbsize=96&pilimit=50&generator=prefixsearch&gpssearch=tomato&gpslimit=50

  Although a nice improvement would be to link to the specific API used.

--Stephen


On Thu, Apr 30, 2015 at 6:00 PM, Jon Katz <jkatz@wikimedia.org> wrote:
+S (not sure if you're on this list)

On Thu, Apr 30, 2015 at 3:27 AM, Joaquin Oltra Hernandez <jhernandez@wikimedia.org> wrote:
Personally, I would love hand crafted awesome documentation and full versions of the API. From developers, to developers, with care.

As an example, the github api is very good: https://developer.github.com/v3/issues/ for example.

And for me the gold in api docs is the stripe ones : https://stripe.com/docs/api/curl#retrieve_customer So useful, calling and responses examples in several languages, OHH so good.

Such a pleasure to read and use and the confidence that if you are using a version, it's not going to change under your feet.






On Thu, Apr 30, 2015 at 10:06 AM, Sam Smith <samsmith@wikimedia.org> wrote:
A simple first step would be to tag the FIXMEs with a small set of tags, like half of Jon's examples already are.

–Sam

On Wed, Apr 29, 2015 at 7:10 PM, Brian Gerstle <bgerstle@wikimedia.org> wrote:
Great thinking, Jon! I'm sure that didn't even catch everything. I know there are some comments like that in the iOS repo, but aren't as easy to detect.

Would be great if each client had a system for flagging & cataloging this kind of tech debt.

On Wed, Apr 29, 2015 at 2:03 PM, Jon Robson <jdlrobson@gmail.com> wrote:
master x ~/git/core/extensions/MobileFrontend $ ag 'FIXME:.*API'

javascripts/modules/editor/EditorApi.js

67: // FIXME: MediaWiki API, seriously?

73: // FIXME: API - missing is set to empty string (face palm)

183: // FIXME: AbuseFilter should have more consistent API responses


javascripts/modules/gallery/PhotoListApi.js

76: // FIXME: [API] have to request timestamp since api returns an object

116: // FIXME: [API] in an ideal world imageData would be a sorted array

124: // FIXME: API I hate you.


javascripts/modules/nearby/NearbyApi.js

144: // FIXME: API bug 48512

153: // FIXME: API returns object when array would make much sense


javascripts/modules/uploads/PhotoApi.js

253: // FIXME: API doesn't return this information on duplicate images...


resources/mobile.mediaViewer/ImageApi.js

54: // FIXME: API


resources/mobile.startup/PageApi.js

148: // FIXME: [API] the API sometimes returns an object and sometimes an array

211: // FIXME: API returns an object when a list makes much more sense

215: // FIXME: "|| []" wouldn't be needed if API was more consistent

_______________________________________________
Mobile-l mailing list
Mobile-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mobile-l



--
EN Wikipedia user page: https://en.wikipedia.org/wiki/User:Brian.gerstle
IRC: bgerstle

_______________________________________________
Mobile-l mailing list
Mobile-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mobile-l



_______________________________________________
Mobile-l mailing list
Mobile-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mobile-l



_______________________________________________
Mobile-l mailing list
Mobile-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mobile-l



_______________________________________________
Mobile-l mailing list
Mobile-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mobile-l