I just read through a good chunk of this, hoping it'd be a good resource.

There's a lot of good stuff in here:

- Higher level than a spec, but still detailed.

- He outlines the anatomy of an HTTP request and gives examples.

- Lots of good suggestions of conventions and rules of thumb, e.g. for URL structure and naming.

- Good demonstration of why using fitting HTTP verbs is important. Explains idempotent and safe.

On the flip side, his ethos isn't the best at points, he presents some subjective takes as fact, and even includes some plain errors against the specification.

For example:

- JSON keys should be snake cased, or camelCased "if you're one of _those_ people". (I'm a snake case guy, but really?)

- Return a 400 if there are any problems with the request. (400 explicitly means request body can't be parsed, e.g. syntax error in your JSON. The spec isn't perfect, but 422 is often more fitting if the consumer input didn't pass validation. Either way 400 clearly violates the spec.)

- He misses the nuance of what PUT is in the spec. You're saying "store this resource at this URL". Not technically update. Although in practice it's usually update, and I'm sure this point will be viewed as pedantic by many.

Overall a decent resource, but take it with a grain of salt.

I read this book for a public API project I was working on. At the time I had done several Rest APIs but for internal use. When it came time for a public API, you really need to up your game. A public API says a lot about a company. It's essentially marketing and sales plus a way to interact with your company programmatically. This book covers all your basics of Rest API design.

Another topic to read up on intent API design (intent resources). If you stick to nouns as your resources, you will encounter issues with naming APIs that have several steps or are really executions of business processes/procedures. With intent resources, you can continue to use the noun paradigm for naming your APIs but still be able to have complicated APIs (more than just simple CRUD).