Why we are building on REST, for now
Boring, ubiquitous, and debuggable with tools every developer already has. The alternatives are more interesting and that is the problem.
We have been asked a few times why the gateway speaks plain REST over JSON rather than something more considered. It is a fair question. The answer is that we are optimising for the first ten minutes.
The first ten minutes
Someone lands on a listing, copies a curl command, pastes it into a terminal, and sees a response. If that works, they keep going. If it requires installing a client library, generating stubs from a schema, or learning a query language first, a meaningful fraction of people stop.
curl, Postman, and a browser address bar all speak REST. That ubiquity is worth more to us right now than elegance.
What we looked at
SOAP still turns up in enterprise catalogues and we will support it at the edges where a provider only offers it, but nobody is choosing it for a new integration in 2015.
Facebook's GraphQL is the interesting one. The specification came out this spring and the ideas are good — asking for exactly the fields you want solves a real problem with chatty REST endpoints. It is also months old, the tooling is thin outside one company, and we would be asking every provider on the platform to model their data twice. We are watching it rather than betting on it.
Hypermedia and HATEOAS get argued about more than they get used. We link related resources where it helps and do not pretend the API is self-describing.
What we are strict about
Being unambitious about the protocol means being strict about everything else. Every response is JSON with a top-level success boolean. Errors carry a stable machine-readable code, not just a sentence. Pagination works the same way on every endpoint. Dates are ISO 8601 in UTC, always, with no exceptions for providers who prefer otherwise.
Consistency across forty APIs is the thing we can offer that no individual vendor can. That is where the effort goes.