Today at The Ultimate Developer Event, Jason Lengstorf provided 4 technical keys to building better REST APIs. Jason is Founder of Copter Labs, a web design and consulting company based in Portland, Oregon. In his mind, these keys are all simple, as long as you stick to the basics.
1. Choose Simple, Easy-to-Read Identifiers
The idea is to write the code in an easily readable manner, that benefits the user. Choose identifiers that are logical and representative. Jason explained it this way:
“When I was first starting to develop, I had this idea that what I needed to do was write the most efficient code possible, and that meant the fewest number of characters... In doing so I would make my code extremely hard to read. Over time, as I would go back into my code and learn just how awful that really was. I started writing out full variable names.”
2. Use the Correct HTTP Method for Requests
“This is something that took a while to get my head around when I was first getting into this." explained Lengstorf "Coming from a web development world, I never did a lot of straight HTTP requests. Things like PUT didn’t really make sense. I only understood GET and POST... It is important to take the time and learn the way that they work and make sure that you are implementing them correctly. So that people can actually interact in a way that is proper.”
3. Return The Correct Status Codes
It turns out that there are more error codes than just the dreaded 404. Jason suggests that developers embrace the multitude of error code options and choose the one that is most fitting, not just the most broad.
“There are actually a ton of these [HTTP Status Codes] and I would encourage taking a look at them to see what's available... so you're not always just sending 200, when somebody has updated a post, you should probably be sending a different code.“
4. Provide Links to Explore the API Further
The key here is to understand when and how to provide information. If the request is looking for information on a specific user, providing access to information on all users probably isn't much value; providing information on a related subset of users does.
"Related content is supposed to be discoverable [from within the response]."
Also, remember to check out yesterday's coverage of the The Ultimate Developer Event's Backbone.js and CoffeeScript workshop.