As we spend the next few weeks honing and building out new features in Brightwork, we wanted to spend a moment acknowledging those that have come before us to build solutions using RESTful APIs. And while there have been spirited debates all over the internet about what is better in terms of sticking to Roy Fielding's vision of RESTful APIs, it has been widely pushed aside for more pragmatic versions.
So who is right in this ongoing discussion about API best practices? Well, the easiest answer is both. However, it really depends on what you are building and whether or not you need to have all of the standards built in that Mr. Fielding talks about in his dissertation on Representation State Transfer (REST).
Spencer Schneidenbach wrote a great medium post about the two main rules for RESTful API design.
"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."
From my experience the last point is super important. I've seen a myriad of APIs out there try to reinvent the wheel when trying to provide information about why an API failed. They believed that they were special.
At the end of the day, you want something that provides a real service, but doesn't try to take you down a path of being too complex that you spend more of your time wondering what the hell you did instead of simply growing and building.
I'm not going to bore you with a ton of technical content here. There are a ton of articles and blog posts that outline the best practices of RESTful APIs. I've copied some links below to get you going. Happy building!
Roy Fielding's dissertation on Representation State Transfer (REST)
How RESTful is Your API? by Cory House
RESTful API Best Practices and Common Pitfalls by Spencer Schneidenback