Core Merging Plan for the API

[rmccue]

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 #717
• [ ] Create internal structure for linking routes to object types: #578
• Switch to request object instead of magic reflection argument matching: #556
• Discoverability for write permissions: #574 (owned by @joehoyle)

Server Code (Routing, Serialisation, etc)

• Convert bit flags to array-based: #544
• Convert numeric-indexed route map to associative ([0] -> ['handler'], [1] -> ['methods']): #544
• Ensure route parameters are pluggable for future use: #556
• Add registration functions, including forced namespacing and versioning: #556
• Add enveloping support for non-capable clients/servers: #370

Other Infrastructure

• Create base controller class: #556
• Split non-essential code from plugin.php (JS loader, etc): #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 ) #693
• Migrate Media class to new Controller style (@danielbachhuber)
• Migrate Meta class to new Controller style (@rmccue) WIP #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: #554
  • Field names
  • Query arguments: #555
• 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 #693 (@rachelbaker)
• Add create, update, and delete endpoints: #86, #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 (#816)

Schema

• Set endpoint properties from the schema #844
• Add type registration (register_post_type) parameters for API controllers #769
• 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: #572 (as a plugin)
• Add batch request support: #561
• Add parameters to link routes to specific object types #577, #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

[rachelbaker]

Excellent!

[rmccue]

I think we're pretty much done with step 0, so marking as done. 👏

[cannyboy]

I'm curious, is WP-API on track for integration into WP 4.1 (approx 10 December)?

[danielbachhuber]

I'm curious, is WP-API on track for integration into WP 4.1 (approx 10 December)?

There's no fixed timeline for integration into core at this time.

[cemdev]

Still no fixed timeline for integration into core?

[danielbachhuber]

Still no fixed timeline for integration into core?

Getting closer!

[rachelbaker]

Updated this issue to represent latest priorities/progress:

• Added Schema section to Step 1.
• Marked Merge avatar URL function into core as complete.
• Added a few related PR or Issue numbers to remaining open or in-progress tasks.

[joehoyle]

Add batch request support: #561

#561 doesn't seem to be about batch requests support - for example see @danielbachhuber's latest comment there:

@rmccue how would I make a batch request where the second request is dependent on the result of the first?

This is conflating two issues I think. Sending multiple requests as a matter of convenience to reduce HTTP requests shouldn't be conflated with "How should we support creating multiple Resources in one request" as that brings the complexity that Daniel highlights above. It seems we need a ticket to just support multiple parallel independent requests which would return each response enveloped in someway.

[rachelbaker]

Updated to mark the following as complete:

• Migrate Media class to new Controller style
• Use JSON Schema to define schemas for our Controllers
• Split plugin.php and class-wp-json-server.php into separate directory

[rachelbaker]

Updated to represent our progress thus far as we release v2.0 Beta 1.

[chriscct7]

Investigate upcoming PSR-7 and possibly change WP_HTTP_Response to match

PSR 7 is now accepted

[chriscct7]

Related #1542

[danielbachhuber]

@rmccue Can you revise this plan to reflect what we need to do by end of January? Alternatively, I'm open to closing, and just using the 2.0 milestone for everything between now and then.

[rmccue]

We are now merged.