Centralized API handbook

[casiepa]

I'm working a lot with APIs all over the WordPress world:

• The standard APIs from ​https://api.wordpress.org have a global description on ​https://codex.wordpress.org/WordPress.org_API
• The API from Central (to get info from the WordCamps) has just a short reference at the bottom of the page on ​https://central.wordcamp.org/schedule/ but I'm not sure further documentation exists
• The WordPress.tv API has been recently extended with lots of info, but no documentation exists
• The translation API can provide lots of information on localization of projects, plugins and themes, but not sure also there is any information exist.

A centralized handbook with all API info, including parameters and extended with examples would a really a great tool for developers.

I can provide all info for the WordPress.tv one and can provide lots of examples for the other ones, so please let me know how we can work on this together.

[Kenshino]

Hey - I'm quite supportive of this.

This does change DevHub's role slightly - in the manner that it'd not just be the holding place for WordPress development code reference and handbooks. But it'd also hold the docs for developing against the WordPress.org infrastructure.

It still holds through for the persona mandate - as a developer, I should only need to go to DevHub to get all my information.

What do you think @coffee2code ?

[casiepa]

Waiting for a final place, I published some WordPress.tv API info on ​https://make.wordpress.org/tv/handbook/wordpress-tv-api/

[coffee2code]

I'm on board with hosting API document in DevHub. APIs are generally a developer-related sort of thing and having them centrally located alongside other dev docs seems reasonable.

Looking at it from another angle, I'm not sure where else would be better for API docs to be hosted. The alternative for many, like the WP.tv API, would likely be in the handbook on their team's Make site, but those sites are intended for contributors. It muddies their purpose if developer-focused or user-focused documentation also exists there.

[atachibana]

I am 100% agree to "APIs Handbook" that will gather WordPress.org APIs and Core APIs listed in right side of ​https://developer.wordpress.org/reference/. Currently, Plugins Handbook covers some of them but many API entry pages remain in Codex. If we can provide them in DevHub, developer must feel convenient.

I have some proposal based on the last docs team meeting with @Kenshino and @milana_cap

Page Structure

Each API page (except REST API, which has independent handbook) should have Overview, Description, Usage examples and list of functions.

Table of Contents

• Dashboard widgets
• Database
• HTTP API
• Filesystem
• Metadata
• Options
• Plugins
• Quicktags
• REST API
• Rewrite
• Settings
• Shortcode
• Theme Modification
• Transients
• XML-RPC
• WordPress.org
• Central (for WordCamp)
• WordPress.tv
• Translation

Creation Workflow

1. (meta) Create page structure under the ​https://developer.wordpress.org
2. (docs) Migrate Codex Pages or Copy from Themes/Plugins Handbook to there
3. (core) Review and Update by the Core reps. Some of contents might be out of date.
4. (docs) Release

[coffee2code]

In 8961:

Developer: Create Common APIs handbook.

Handbook is currently only accessible to logged-in users.

See #4376.

[coffee2code]

In 8962:

Developer: Customize section title for Common APIs handbook.

See #4376.

[coffee2code]

The Common APIs handbook has been created and accessible (only to logged-in users) via ​https://developer.wordpress.org/apis/.

I've held off on adding a DevHub front page block for it until later. Relatedly, the details for the block could stand to be agreed upon. Currently I have:

• Dashicon: ​https://developer.wordpress.org/resource/dashicons/#admin-site-alt3
• Block description (in the form of a question): "Interested in interacting with various APIs?"
• Link text: "Utilize APIs"
• Position: first block in second row (when each row displays 3 blocks)

This ticket can be closed out once the handbook has been added to the DevHub front page and made publicly accessible.

@casiepa: You're already a handbook editor, but be sure to coordinate with the rest of the Docs team to confirm the structure and style of the handbook before getting too far with things.

[coffee2code]

In 9172:

Developer: Make Common APIs handbook publicly accessible.

See #4376.

[coffee2code]

In 9173:

Developer: Add block for Common API to homepage.

Fixes #4376.

[coffee2code]

The handbook was officially approved to be made publicly accessible via See ​https://wordpress.slack.com/archives/C02RP4WU5/p1570688069008800?thread_ts=1570645228.002900&cid=C02RP4WU5

I went ahead with adding a block for the handbook to the homepage. Any aspect of it can be changed, if desired.