How to Design Better APIs

The error messages could be better yet.

The example uses a different code per issue, for instance: "user/email_required". Most integrators will build their UI to highlight the input fields that contain an error. Making them parse the `code` field (or special-case each possible code) is pretty toilsome.

    // from blog post
    {
        "code": "user/email_required",
        "message": "The parameter [email] is required."
    }

Make it parseable:

    // improved
    {
        "message": "An email is required.",
        "error": "missing_parameter",
        "parameter": "user.email"
    }

In addition, I:

* rewrote `message` to be an acceptable error message displayed to (non-technical) end-users

* moved message to be the first field: some developer tools will truncate the JSON response body when presenting it in the stack trace.

---

As an added bonus, structured data allows you to analyze `error` frequencies and improve frontend validation or write better error messages: https://twitter.com/VicVijayakumar/status/149509216182142976...

Some nice tips in here. However, tip 15, I strongly disagree with:

> 15. Allow expanding resources

I would suggest the opposite. A REST API should not return nested resources at all. Instead, and to stay with the example provided on the website, to obtain the "orders", the /users/:id/orders endpoint should be called.

It might be tempting to return nested resources, because clients would only have to make a single call.Technically this is true but once the domain of your API starts to grow, you will find that the interface will become increasingly muddled.

The suggestion provided (use query parameters) is basically a work-around. If you want to offer this to your clients, front your REST API with a GraphQL API instead. It is literally the problem that GraphQL solves. Keep your REST API clean and dumb and focused around CRUD.

Human readability most likely

Dear PAM69, this is great advice if you want to end up with a slow-to-load, low-performing web application that your customers complain about and hate using. But at least it'll adhere to a specific notion of architectural "purity", right? /s

Anytime clients need to make 15 async calls before the UI can be displayed, you're headed up the creek. Generally speaking, this is an anti-pattern. There are exceptions, but they're not the rule.

It's better to weigh the tradeoffs in any given situation and make a decision about bundling sub-resource references based on what you're optimizing for.

A few quick examples:

* Dev speed: Unbundled

* Quick-loading UI: Bundled

* Sub-resources are computationally-expensive to query? Unbundled

This has been my experience consistently throughout 20 years of web-tier development.

1. Human readability

2. The ISO date format is "big endian" by default, which makes it trivial to chunk and compare just specific date parts. Want all events that occurred on the same (UTC) date? Just do dateField.substring(0, 10). Everything in the same year? dateField.substring(0, 4).