I recently had the opportunity to have a discussion about API design and RESTful services with Vasusen Patil. I’ve also been having quite a few conversations of similar nature with Justin Davis over the last few months. These types of conversations are some of my favorite because, for the most part, there are no right answers and many many interpretations.

I’ve been on both sides of these conversations as of late. At work, I am in the trenches with API consumption. With my PHP framework, Pickles, I have been in the middle of a rework that would move away from being a system for building websites and moving towards a system for building services.

At work I have been given the opporunity to see how upwards of 30+ different companies with similar products would implement the same API system. Even with OpenTravel standards, there is still quite a divide on how to do things. At this point, I’ve got my own thoughts and ideas on how to do things. I wanted to get them out of my head and into my blog for posterity’s sake. Let’s be honest, as engineers, our ideals tend to change over time and it’s always good for a laugh to look back at things ;)

Endpoints

I’ve been guilty of it in the past, but these days I will do whatever I can to keep any verbs out of the endpoint names. Somewhat trivial, but I prefer my endpoints to be all lowercase. When IDs are involved, I like to use integers and I like them to occur after the noun. Example: /user/1/place/2.

Request Methods

Even though PHP doesn’t do me any favors with $_PUT or $_DELETE I do prefer to break up actions by request method. My logic behind doing so is because I’m not a fan of including an “action” parameter to determine what we’re doing. It keeps the requests a bit cleaner but at the sacrifice of being harder to implement in some languages compared to just using $_GET and $_POST.

Responses

JSON for life, or at least something better comes around. I’ve worked with enough XML to fill at least a dozen lifetimes and simply do not like working with it.

Status Codes

I like em and I use them. In addition to leveraging the status code in the header, I also put it in the response body (as part of the meta section).

Error Messages

In addition to the status code, I always include a message, even if the call was successful. The message is part of the meta section of the response and can be as terse as “OK” or as verbose as “The user profile was updated successfully” or “The request was missing the %s parameter”. I am not a fan of cryptic internal error codes and having to go dig back through documentation to figure out what they mean, returning explanatory messages helps a ton.

Versioning

Versioning as a whole could probably be it’s own blog post at this point. I’m a fan of having a major version number (integer) as part of the request, /v1/user for example. By itself this is great for systems that receive updates infrequently. HolidayAPI is a good example as the API hasn’t been changed in at least a year or so.

Also, there is a school of thought that the version in the endpoint is not as semantic as including it in the request header. I can definitely agree with that but at a certain point it’s just nice to look at the endpoint and know exactly what version you’re working with.

The major version number works for slow to update systems but can all fall apart when you have an API that is hacked upon daily. The major version number is still a good indicator of things, but you will probably need to include a revision number of sorts to do further version abstraction. This gets even more fun when you think in the scope of versioning the entire API or just the a specific call.

Once you’ve made the decision, how do you handle that in your code? This is why I enjoy these kinds of conversations, they can be as mind boggling as you want them to be :)

Rate Limiting

Yes. Even if the rates are very high, you still need something in place to keep abuse to a minimum. At this time I’m actually unsure if rate limiting should be built into the service’s code or should be handled by the server with something like this.

Code Reuse

Going back to versioning, I prefer that each version of my API does not rely on any code from the previous version. If that means just copying over the entire system as your first step so be it. It’s not pretty but it eliminates the situation where a change in one version could impact the other version which is not ideal at all.

To take this a step further, I like each of my endpoints to function without anything from another endpoint. Same logic as above, I don’t want to run into issues where the dependencies break other calls. Still not pretty but it gives me piece of mind. I still have some reuse by way of using the same ORM and utility functions, so it’s not a complete vacuum chamber.

This lack of reuse actually stemmed from how I started writing my unit tests recently. With my tests, I didn’t want to have to run the entire harness just to test a single class. Because of this, I started to write each test class to provide 100% coverage for the entire file, instead of relying on tests in another class to fill in the gaps. It results in more tests but it means if you drop a class and tests from your system, the code coverage will not dip.

Responses

This is a fun one because I have a few assumptions and then some blank spots. When adding a new record or editing the record, it’s a no brainer, you can return the ID and/or the entire record (which could then be used as an echo). What about when you delete a record? I’m actually still not sure on this one. You could return the ID and/or the entire record just for consistency with your other calls. You could also omit the response body entirely because you deleted the record and there is nothing to give back. Another route would be to include “deleted” in the response or perhaps in the “meta” section and continue to leave the body blank. Only The Shadow knows.

I’ve already mentioned it, but I like to break my response into a “meta” section and an optional “response” section. Meta contains everything that’s not related to the data being returned. Including but not limited to the status code, message, API version / revision, any echo token that was provided, et cetera.

Conclusion

At the end of the day, the only truth for me is that there aren’t really any wrong answers as long as your API performs well. If it doesn’t perform well at the very least degrade gracefully. I run into a lot of APIs that simply can’t handle a flood of calls and it cripples their entire API. A lot of times the “flood” of calls I’m making is one every couple of seconds, far from an onslaught ;)

Would love to continue this conversation down in the comments, feel free to join in!





Did you enjoy this post?

Cool if I slip into your inbox with more?
Full posts, 1-2 times per week: