The key to getting the API into core is breaking the merge into steps. I've been talking these through with the rest of the team at WCSF, and we're going to break this up into a few basic steps.

Each of these steps has challenges, but the idea is to try and handle these step-by-step to chip away at the larger task.

At the end of each step, we'll stop and make sure we've completed everything we wanted to, ensure we have nothing else to do, then shepherd it into core. The next step doesn't start until the previous is fully complete.

The actual process of finalising each step will be to separate the relevant code into a separate repository, then formatting it as a core patch. These can then be reviewed separately, and merged into WP core at the behest of the core team. (The actual timing for this depends on the release cycles and such, but
this doesn't need to affect our work.)

Step 0: Reinvigorate the two-dot-oh branch      ✓
Step 1: Pushing ahead with infrastructure       ✓
Step 2: Making our core objects available       * YOU ARE HERE
Step 3: Periphery                               .

Step 0: Reinvigorate the two-dot-oh branch

We've decided internally that the resource approach taken on two-dot-oh isn't going to work. In short, the benefits we imagined didn't really turn up, however we did learn some about our approach here. We'll handle that in a later step.

There's plenty that we've done on the two-dot-oh branch that's still applicable, so we should salvage these now before they diverge any further. Ideally, this means no new code, just judicious use of cherry-picking.

• Cherry-pick non-resource commits from two-dot-oh

  • Dropping backwards compatibility shims
  • Switching to HAL from our custom linking format
  • Switch from */*_raw to *.rendered/*.raw
  • Make the response class generic

• Cherry-pick (or otherwise bring across) any changes to users.

  (There are some non-resource-related changes in the branch that fix bugs or add features missing on the master branch right now.)

Step 1: Pushing ahead with infrastructure

The first part up for merge is the infrastructure. This is the bare basics to run any sort of API, and will consist primarily of our plugin.php and lib/class-wp-json-server.php files.

• Split plugin.php and class-wp-json-server.php into separate directory Split core infrastructure into separate directory #717
• [ ] Create internal structure for linking routes to object types: Add route discovery based on type #578
• Switch to request object instead of magic reflection argument matching: WP_JSON_Controller POC #556
• Discoverability for write permissions: Write permission discoverability for endpoints #574 (owned by @joehoyle)

Server Code (Routing, Serialisation, etc)

• Convert bit flags to array-based: Change internal routing structure to non-bitmask #544
• Convert numeric-indexed route map to associative ([0] -> ['handler'], [1] -> ['methods']): Change internal routing structure to non-bitmask #544
• Ensure route parameters are pluggable for future use: WP_JSON_Controller POC #556
• Add registration functions, including forced namespacing and versioning: WP_JSON_Controller POC #556
• Add enveloping support for non-capable clients/servers: Add ability to get status as different header (support HTTP envelope) #370

Other Infrastructure

• Create base controller class: WP_JSON_Controller POC #556
• Split non-essential code from plugin.php (JS loader, etc): Initial Extras.php commit #575

Step 2: Making our core objects available

Once the infrastructure is in core, let's work step-by-step and evaulate our core objects. These are the Core Objects: Posts, Comments, Terms and Users. This also includes meta for each (except terms).

This does not include options or similar (plugins, themes, customiser endpoints,
etc).

(PCTU = Posts, Comments, Terms and Users)

• Create Post Type base for new Controller style
• Migrate Posts class to new Controller style (@rachelbaker)
• Migrate Comments class to new Controller style (@joehoyle @rachelbaker ) Comments Endpoints #693
• Migrate Media class to new Controller style (@danielbachhuber)
• Migrate Meta class to new Controller style (@rmccue) WIP Add New Style Meta Endpoints #928
• Migrate Users class to new Controller style (@rachelbaker)
• Change PCTU classes to take a type as first parameter (CPT, custom comment type, taxonomy) where applicable (excluding users)
• Move preparation methods to public API (also, ensure preparation is decoupled from permission checking, to avoid using global state there)
• Audit for consistency
  • Pagination: Consistent pagination arguments across the board #554
  • Field names
  • Query arguments: Consistent collection query arguments across the board #555
• Use JSON Schema to define schemas for our Controllers Use JSON Schema to define schemas for our Controllers #759
• Include permissions in response: In Discussion

Collections

• Switch collections to returning objects
• Return pagination params in response: current page, next link, prev link, total pages, total items

Posts

• Switch Posts class to extend CPT class
• Remove Last-Modified header

Comments

• Split comments out to separate controller Comments Endpoints #693 (@rachelbaker)
• Add create, update, and delete endpoints: Add endpoints to create, update and delete comments #86, Comments Endpoints #693 (@rachelbaker)

Terms

• Check on status of term_id/term_taxonomy_id unification in core

  (Depending on this, we may need to change the way the API works with IDs.)

Users

• Conduct extra audit for privacy and security purposes

Options

• Add basic options/settings API, initially for whitelisted options only (Options Endpoints #816)

Schema

• Set endpoint properties from the schema JSON Schemas for our Controllers, second attempt #844
• Add type registration (register_post_type) parameters for API controllers Register post types for API based on access_in_json argument #769
• Add object type-to-route mapping to index for discoverability Add object type-to-route mapping to index for discoverability #577 (owned by @rmccue)

Step 3: Periphery

Now that core has the vast majority of the API in place, it's time to worry about all those extras we missed out on the way.

• Split cookie authentication out
• Merge various date utilities into core: WP28636
• Merge avatar URL function into core: WP21195
• Merge json_last_error shim into core (integrate with Services_JSON)
• Merge JsonSerializable shim into core (integrate with wp_json_encode)
• Merge the Backbone-based JS API
• Merge OAuth 1.0a authentication
• Investigate upcoming PSR-7 and possibly change WP_HTTP_Response to match
• Add fields argument to filter response fields: Add field include/exclude parameters to change which fields are returned #572 (as a plugin)
• Add batch request support: How should we support creating multiple Resources in one request? #561
• Add parameters to link routes to specific object types Add object type-to-route mapping to index for discoverability #577, Grand unified theory of content types #718

Post-Process

Once the process is complete and the API is merged, we can move on to new features outside our main focus. These can also happen in parallel if we have sufficient resources (i.e. people) to handle these as well.

• W.org proxy for OAuth 2.0 and centralisation
• WP.com implementing the API as version 2