Note I plan to come back to this!
TBH we mostly copied the Stripe API
JSON vs url-form-encoded
Stripe – due to a legacy decision – still requires url-form-encoded data for POST requests**.
We decided to use JSON for all requests for three reasons:
- JSON is more flexible and easier to work with than url-form-encoded data. You can send Integer, Boolean, and Null values in JSON without worrying about string parsing. You can also send arrays and objects natively in JSON whereas they're complex (and sometimes ambiguous) in url-form-encoded data.
- JSON is slightly more secure than url-form-encoded data. You have to make a special effort to log a JSON request body, whereas myriad tools throughout your stack log request URLs (including query params).
** Their client libraries abstract this away for most users, but on their end they still have to correctly parse every request