What’s In a Name?

William Shakespeare, via Wikipedia

If you follow API development conventions, regardless of the patterns you follow — coming up with meaningful and useful API routes always proves an interesting challenge. Let me see if I can explain what I mean.

In general you’ll interact with two kinds of APIs doing web application development. RESTful APIs and RPC APIs. And let me tell you, if you have to interact with both kinds of APIs in the same repository, figuring out what is what can get awfully confusing.

Forcing something that’s an RPC call into a RESTful pattern has been cause for much consternation for me over the years. In fact, I still haven’t really figured out the best way to deal with situations where an RPC method seems to be the only way to handle something.

Usually speaking RPC methods exist because we have some kind of cron job that needs to run on some routine basis to do some kind of regular bulk data update. Honestly, more often than not I’m not a big fan of building RPC calls into a web API. These are the kinds of things better relegated to crontab style jobs — but there are times and places where these make sense. I don’t really want to talk about RPC jobs right now, but they can also complicate naming if we’re not careful with how we design API routes.

The most important thing for a web API is the name of the API route that we’re providing. There’s all kinds of recommendations about best practices and standards for how this could work, but the one I’ve found myself most in tune with works as follows:

Base route identification such as

/api/v1
  • Top level object that is a filterable collection. The keyword here is filterable. The names of the filters are important too.
  • This would give you a list of all people. Keep data size in mind — pagination may be something you always have to think about. If people number in the thousands or millions, this record set might be too big to use:
/people
  • This would give you the same list of people, but their first name and last name attributes would match the filter passed in:
  • By sending a POST body with the right JSON format to the API below the API would create a new “people” object
 /api/v1/people 
  • And this would give you the ability to manage the state of a given person:
/people/1
  • GET — returns the person that has ID 1
  • PUT — Updates the state of the person with ID 1, or returns an error if ID 1 doesn’t exist
  • DELETE — Removes ID 1 from the database

Here’s a neat little hint: If you’re wanting to make up some JSON on the spot, and wanting to make sure it’s a valid JSON document — this handy little tool does a great job. I plan on using it pretty frequently as I blog here, in fact.

Getting API naming right depends heavily on consistency. If you can’t come up with a consistent naming convention for where you’re going to find API methods for the state of your database, you’re likely to end up with repeated code and redundancy. Modularity starts to break down, and if one of the methods that’s in two places has an error in it, you have to remember to fix it in both places.

As you write RESTful APIs, take the time to consider the name of the routes you’re going to use. I really prefer the JSON API specification, but this certainly isn’t the only pattern that you can follow to build JSON contracts.

The biggest takeaway is convention and consistency. As long as you build your API with both of these in mind, using it becomes much easier down the road.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.