mwn icon indicating copy to clipboard operation
mwn copied to clipboard

Meet MW API client code gold standard

Open siddharthvp opened this issue 3 years ago • 0 comments

Copying off from the list at https://www.mediawiki.org/wiki/API:Client_code/Gold_standard

Easy to install

  • [x] Installation instructions are correct and easy to find
  • [x] Library is packaged for installation through appropriate package library (PyPI, CPAN, npm, Maven, rubygems, etc.)
  • [ ] Platinum standard: library is packaged for and made available through Linux distributions

Easy to understand

  • [x] Well designed: makes all intended API calls available with the intended level of abstraction with no redundancies
  • [ ] Platinum standard: makes the Wikidata API available

Well documented

  • [x] Code is commented and readable
  • [x] Documentation is comprehensive, accurate, and easy to find
  • [x] Deprecated functions are clearly marked as such
  • [ ] Platinum standard: Documentation is understandable by a novice programmer
  • [x] Code uses idioms appropriate to the language the library is written in

Easy to use

  • [ ] Has functioning, simple, and well-written code samples for common tasks
  • [x] Demonstrates queries
  • [x] Demonstrates edits

Handles API complications or idiosyncrasies so the user doesn't have to:

  • [x] Login/logout
  • [x] Cookies
  • [x] Tokens
  • [x] Query continuations using the new "continue" and not "query-continue"
  • [ ] (?) Requests via https, including certificate validation
  • [x] Courteous API usage is promoted through code samples and smart defaults
  • [x] gzip compression is used by default
  • [x] Examples show how to create and use a meaningful user-agent header (as in meta.wikimedia.org/wiki/User-agent_policy)
  • [ ] Platinum standard: generates a unique user-agent string given name/email address/repository location
  • [x] Efficient usage of API calls
  • [x] Can be used with the most recent stable version of the language it is written in (e.g. Python 3 compatible)

Easy to debug

  • [x] Contains unit tests for the longest and most frequently modified functions in the library
  • [x] Platinum standard: Unit tests for many code paths exist and are maintained
  • [x] Terrible hacks/instances of extreme cleverness are clearly marked as such in comments
  • [ ] Documentation links to the relevant section/subpage of the API documentation

Easy to improve

Many of these aren't really applicable -- I have marked such items as checked because there is nothing to be done about them

  • [x] Library maintainers are responsive and courteous, and foster a thoughtful and inclusive community of developers and users
  • [x] Platinum standard: Project sets clear expectations for conduct[1][2] for spaces where project-related interactions occur (mailing list, IRC, repository, issue tracker). It should:
  • [x] State desired attitudes and behaviors
  • [x] Provide examples of unwelcome and harassing behavior
  • [x] Specify how these expectations will be enforced
  • [x] Pull requests are either accepted or rejected with reason within 3 weeks (Platinum standard: 3 business days)
  • [x] Issues/bugs are responded to in some manner within 3 weeks (Platinum standard: 3 business days) (but not necessarily fixed)
  • [ ] The library is updated and a new version is released within 3 weeks (Platinum standard: 3 business days) when breaking changes are made to the API
  • [ ] Platinum standard: library maintainers contact MediaWiki API maintainers with feedback on the API's design and function
  • [x] Library specifies the license it is released under

siddharthvp avatar Jul 14 '20 18:07 siddharthvp