Designing a developer-friendly API

Note I plan to come back to this!

Inspirations

TBH we mostly copied the Stripe API

Exceptions

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.
• Developers expect it. JSON has become much more widely used than url-form-encoded data in the last decade. It's also the default data format for JavaScript fetch requests, and as we return JSON in our API response bodies it makes for a more consistent developer experience.
• 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