5 Tips for Designing RESTful API URI

Sharing is Caring

Each resource in the REST architecture is identified by it’s Uniform Resource Identifier (URI). Changing resource URI’s is very difficult to do once an API is public or that there are clients for it.

These tips are based on providing a uniform interface REST constraint.

Tip 1: Always Pluralize

In our endpoints, we should always use nouns to represent the entity that we’re interacting with. I highly recommend using the Plural version books instead of book.

If you do a GET on /books it should return an array even if it only has one item in the database. If you do a GET on /books/1 or some it should return a book object with an Id of 1.

There are cases where it might make sense to use a resource singleton but those should be very rare.

Tip 2: Always use URI/URL resource identifiers (Id)

The resource Id should always be part of the URI when getting a single resource, updating a resource or deleting a resource. Identifiers should never have special characters or spaces so you don’t end up with cases where the Id is a blank value. I recommend using a guid or uuid and a regex like [a-zA-Z0-9]*

Tip 3: Don’t use Verbs in the URI

Verbs like get, delete, update, or create should not be in a URI. The URI should describe the resource – actions or verbs should be in the HTTP methods.

If you aren’t sure about the HTTP methods, check out the blog article Understanding how to use REST API and HTTP.

Tip 4: Avoid spaces and always lowercase

If you put a space in a URI, it has to be encoded which means that your client’s would need to replace the space with percent encoding.

To make life easier, it’s always best to use simple descriptive nouns to describe each resource. Simple named resources should use lowercase letters and for multiple words use a “-“.

Tip 5: Always use HTTPS

HTTPS uses the SSL/TLS protocol. The SSL/TLS protocol allows us to encrypt communications making it more difficult for hackers to steal data. SSL/TLS also can prevent impersonations or man in the middle attacks.

HTTPS isn’t optional – it’s required for cyber insurance in 2022 and pretty much required by web browsers to make frontend requests to an API.

SSL certificates can be generated for free from most cloud providers, and can be generated for free using Let’s Encrypt. There’s no need to pay GoDaddy $140 a year anymore.

Wrapping it Up

Building RESTful API’s can be difficult but if we follow a consistent process and study best practices it can become a lot easier.

These five tips for creating RESTful URI’s are designed to help you make great consistent endpoints.

Sharing is Caring

Brian is a software architect and technology leader living in Niagara Falls with 13+ years of development experience. He is passionate about automation, business process re-engineering, and building a better tomorrow.

Brian is a proud father of four: two boys, and two girls and has been happily married to Crystal for more than ten years. From time to time, Brian may post about his faith, his family, and definitely about technology.

1 Comments

  1. Pingback: 5 Common REST API Challenges - Brian Cline

Leave Comment

Your email address will not be published.