Search code examples
resturl-routinggithub-apiidentifierapi-design

REST API - string or numerical identifier in URL

We're developing a REST API for our platform. Let's say we have organisations and projects, and projects belong to organisations.

After reading this answer, I would be inclined to use numerical ID's in the URL, so that some of the URLs would become (say with a prefix of /api/v1):

/organisations/1234
/organisations/1234/projects/5678

However, we want to use the same URL structure for our front end UI, so that if you type these URLs in the browser, you will get the relevant webpage in the response instead of a JSON file. Much in the same way you see relevant names of persons and organisations in sites like Facebook or Github.

Using this, we could get something like:

/organisations/dutchpainters
/organisations/dutchpainters/projects/nightwatch

It looks like Github actually exposes their API in the same way.

The advantages and disadvantages I can come up with for using names instead of IDs for URL definitions, are the following:

Advantages:

  • More intuitive URLs for end users
  • 1 to 1 mapping of front end UI and JSON API

Disadvantages:

  • Have to use unique names
  • Have to take care of conflict with reserved names, such as count, so later on, you can still develop an API endpoint like /organisations/count and actually get the number of organisations instead of the organisation called count.

Especially the latter one seems to become a potential pain in the rear. Still, after reading this answer, I'm almost convinced to use the string identifier, since it doesn't seem to make a difference from a convention point of view.

My questions are:

  • Did I miss important advantages / disadvantages of using strings instead of numerical IDs?
  • Did Github develop their string-based approach after their platform matured, or did they know from the start that it would imply some limitations (like the one I mentioned earlier, it seems that they did not implement such functionality)?
Solution

  • It's common to use a combination of both:

    /organisations/1234/projects/5678/nightwatch

    where the last part is simply ignored but used to make the url more readable.

    In your case, with multiple levels of collections you could experiment with this format:

    /organisations/1234/dutchpainters/projects/5678/nightwatch

    If somebody writes

    /organisations/1234/germanpainters/projects/5678/wanderer

    it would still map to the rembrandt, but that should be ok. That will leave room for editing the names without messing up url:s allready out there. Also, names doesn't have to be unique if you don't really need that.