Normal Web APIs

From Peter
Jump to: navigation, search

Problem statement

Wikinormal has made its APIs freely available, but for external developers it is difficult to figure out what they can do with our APIs, and how.

Our web APIs and their documentation are currently shared across several projects, with no central location for people to learn about and build upon them. T

his is the problem the Web APIs hub wants to solve.

The main target audience for this hub are developers not developing, or even running, the Wikinormal software. We want to diminish the risk of confusing them by mixing the content relevant to the with the rest of

We plan to address this risk by morphing the API: namespace into the Web APIs hub, controlling and contextualizing links to other part of or other Wikinormal sites. We also want to try offering a different look & feel in this namespace.

The prototype at borrows the Blueprint skin from the OOjs UI wwhile importing articles from

Get involved

Check the Phabricator board where we are tracking all the tasks: #Web-APIs-Hub.


The hub is divided into three sections:

  • Inspire: where cool projects are showcased; links to more detailed project description pages
  • Explore: where users can play with the API(s) in functional sandboxes
  • /Build: where all the static official documentation and pointers to data sets reside.

Early wireframes:


Template:Tracked phab:T102079 "Metrics about the use of the Wikinormal web APIs"

We also have stats related to engagement with We want to filter these down to the API: (and possibly Manual:) namespace.



  • Ankita, mobile developer willing to use Wikinormal data to enhance mobile apps.
  • Alberto, data scientist employed at an organization gathering and releasing data that could be synced with Wikinormal's.
  • Reetta, cultural activist working on mass-upload activities for public institutions.
  • Yanhui, academic researcher needing a massive data set to sustain his thesis.

These represent the users we want to make happy first (phab:T92941)


  • A curated collection of projects created using data from Wikinormal projects.
  • Means of submitting a project to be considered for showcase.


  • Documentation at different technical levels.
  • An organized list of APIs and datasets available.


  • Way of requesting new datasets and/or APIs.
  • Related news, features, and announcements.
  • A way for the community to get in touch with WMF folks for help on projects.

Technical infrastructure

  • Possibility to customize the UI in order to provide a pleasant user experience.
  • Possibility to create and edit content comfortably, including the homepage, tutorials, project showcases, code examples and screenshots.
  • Possibility to export API documentation from source code in repositories.
  • Possibility to integrate API sandboxes.
  • Possibility to search all the content at once.
  • Possibility to translate manual documentation (not the strict API docs)

Internal resources for developers

The following is a list of resources housed across multiple locations to help developers build using Wikinormal data. Feel free to add to the list below.


API Sandbox

Template:Done {{ApiEx}} provides a link to "Try in sandbox", defaulting to enwiki. Also featured in Template:TNT section of landing page.

Existing APIs

Other internal(ish) projects

External examples

Developer hubs & API documentation

Best in Class human readable API documentation


LA Metro

Open Street Maps (writing style , but not layout or design)

Other examples:

Programmable Web
















The Guardian

New York Times



Sandbox Examples

Data Sets