Separate query builder and transport layer

[kadamwhite]

Goal: Separate the query-builder and transport, as described in "Option A" below.

---

It should be possible to use the query-builder parts of WPAPI without pulling in Superagent. This could result in much smaller bundle size for users who will be consuming the library using fetch, for example, or set us up (or set up consuming developers) to create their own transport layer using axios or other options.

Goals:

• Permit usage of the query-builder part of the library without including any HTTP transport
• Permit clearer path for consumers who wish to bring their own transport object

Option A, which we explore in 2.0.0-alpha.0 and #409: wpapi contains query builder, wpapi/superagent contains a version of WPAPI with the superagent HTTP transport.

Pros

• Makes transport selection an explicit action on the part of the library author; we could add wpapi/fetch and wpapi/axios quite easily
• Clarifies that the core purpose of this library is the query-building, and that the transport's simply a useful secondary benefit.

Cons

• Breaks existing behavior of require( 'wpapi' )
• Makes it harder to tell how superagent dependency should be declared (see below)

Option B: wpapi remains as-is (superagent-specific), and wpapi/core or wpapi/query contains the query-builder-only part.

Pros

• No change to how the library is imported for existing users
• Metaphorical consistency between the wpapi/query import, which reads as "give me just a piece of wpapi, and the actual desire of "give me just the query builder of wpapi"

Cons

• Harder to include alternative transports like axios or fetch in the core bundle, because there would be undesired asymmetry between require( 'wpapi' ) (superagent) and require( 'wpapi/axios' ) or some such.

Open questions:

• Do we continue to include superagent as a dependency, make it a peerDependency, or drop it as a dependency altogether, instead instructing users they must install it if they wish to require wpapi/superagent?
• Should wpapi/superagent in fact be distributed separately its own module, wpapi-superagent? This would certainly clarify the peerDependency question, if we had wpapi, wpapi-superagent and wpapi-axios e.g.. This would possibly make it a little more complex to test the different transports with the same integration suite, even with a monorepo. Additional con: I personally find monorepos difficult to maintain and contribute to, and introducing additional friction to the maintainer process for this project probably benefits noone.
• Should we include transport options using Axios and Fetch in the core package, as well, as discussed in Option A?
• What gotcha's or issues might I be missing?

[Shelob9]

I'm currently using this client in a few places. I like the public API of the query builder. I don't love that I can't provide my own transport. If I could pass my own instance of fetch - or a mock - that would make my bundle smaller and testing easier.

I like option A. A breaking change to update to 2.0 is fine by me. I try and wrap the site discovery process in a reusable function, so the backwards compatible breaking change is a minor fix.

https://github.com/Shelob9/server/blob/82962536c76957a93931985350575809bf1d2e16/src/index.js#L10

[kadamwhite]

Based on conversations on twitter, slack, in person, and @Shelob9's comment above—which was corroborated by other sources—we will be continuing with Option A / #409.