RESTful API Best Practices and Common Pitfalls

As a person who spends his day integrating systems, I’ve found that at least half of the APIs I use radically differ from REST semantics, make changes too often and too quickly, don’t validate enough, and/or don’t have proper documentation. There are tons of resources for making good RESTful APIs already, but I thought I’d add to the mix with some semantic rules and some technical ones that I see broken over and over.

Now, I’m not advocating that you should spend your time trying to implement a fully-compliant REST API — very few have and there’s not much benefit to doing so. I’m a believer in pragmatic REST — that is, you should do what makes sense and throw out what doesn’t. I’m being vague on purpose because it really comes down to your particular use case.

Honestly, good REST design practices could fill an entire book. For the sake of brevity, I’ve chosen ten– four related to technical implementation, six related to semantic. The examples are done using ASP.NET Web API, but the semantic stuff (and the technical, conceptually!) also applies to RESTful APIs made using other web frameworks and languages.

When it comes to RESTful API design, I have two main rules.

1. Do what’s expected. No reason to get creative — a really creative API is probably a bad API. Follow established best practices.
2. Be consistent. Use the same endpoint structure, HTTP status codes, HTTP verbs, etc. for your requests, for the same reasons. A poorly formed request should return 400, not 404.

Continue reading on Medium.