7 Rules to Follow for REST API URI Design

REST APIs use URIs to address resources. While they’re known as opaque identifiers (meaning you shouldn’t read too much into them), there are better and worse ways to write URIs. Guy Levin over at RestCase has formulated a set of design rules for API URIs that you should keep in mind to make things easy for your API clients.

Rule one is a simple one. Don’t include a trailing forward slash in your URI. It adds nothing and might cause confusion or issues for your clients.

Rule two is that forward slashes should be used to indicate hierarchical relationships. Put them in the path portion to show the relation between resources.

The third rule is to use hyphens to improve readability. Developers need to be able to quickly scan and interpret URIs and hyphens function like spaces to improve the readability of long paths.

Rule four is that while hyphens are fine underscores most definitely are not. Text viewers apps often underline URIs, which means your underscore will be hidden.

The fifth rule is: use lowercase letters where you can in paths. Capitals can cause problems because while standards say URIs are case-sensitive, they’re not for scheme and host components.

Rule six: don’t use file extensions in URIs. Use the media-type in the header to make it clear how content should be processed.

Lastly, rule seven: use the plural with endpoints. That means, ‘people’ not ‘person’, ‘geese’ not ‘goose’. Sticking with the plural is simpler for the API client because it means he doesn’t have to deal with irregular plurals.

Guy concludes by stressing that, since each resource is going to have at least one URI identifying it, that URI should make sense and describe the resource. With this in mind, he advises creating a predictable, hierarchical structure to ensure usability. Keeping to the above rules, you will write REST APIs that will be cleaner and easier to understand ensuring a happy consumer.

Original Article

7 Rules for REST API URI Design

Seamus Holland