REST or REpresentational State Transfer is an API architecture style that uses a uniform interface. A REST API is a type of API that is designed to be very flexible but follow the REST constraints. It’s important to remember that REST isn’t a standard or a protocol. It’s a set of architectural constraints.
When designing a REST API we need to really think of the different challenges that can occur. While many of these challenges are related to ignoring the REST API Constraints, there are definitely other issues that will pop up as you work.
Endpoint Consistency
Endpoints or the individual URIs of the API need to be designed to be consistent. I recommend always pluralizing the different entity’s names, so “books” instead of “book”. Verbs should never be used in the URI – so don’t have an endpoint that is /getBooks instead use the HTTPS Verbs and send a GET request to /books.
Every endpoint in the API should do things consistently, filtering should always be done the same way, paging always done the same way and so on. It shouldn’t matter whether you use microservices or one big ol’ ball of string.
In the blog article, 5 Tips for Designing RESTful API URI’s it’s discussed in more detail.
API Versioning
Deciding how or when to version an API is something that needs to really be decided up front – before there are any clients. Versioning allows you to potentially make breaking changes to the API without impacting current users.
Future users won’t go through the breaking changes because they’ll be calling the latest version. I recommend using the version in the URI because then it’s explicit and caching can still be supported.
For more details on versioning see the blog article Versioning in REST APIs.
Increasing Response Times
When an API first launches, it will have it’s lowest volume of data. After a few months or years, the amount of data it has available in databases will be much higher.
Nobody wants to wait minutes for an API to respond – so we need to look at designing searching through filtering, paging or sorting.
And, pro tip: these methods are usually fastest if done through the database.
Caching is a great way of improving API speed. See the blog article 5 Tips for Better Caching in a REST API for ways to improve caching.
Requests containing unneeded data or large volumes of data
Over time, the amount of data we collect and return is likely to increase in size. The more data we are querying and returning the slower the API will potentially become.
I recommend not returning Subdocuments or Subobjects and instead using a HATEOAS approach and providing a link for more details. For example, an Authors endpoint can provide a list of authors and a link to each of their lists of books.
Security
Security is really important when building an API because it can’t be easily updated later. A broken, exposed or hacked API could cause a business a millions of dollars in fines or even result in the business shutting down.
When thinking about security, there’s a lot more to it than just what Authentication scheme are we going to use. oAuth, Basic Auth, Tokens, maybe something else? It doesn’t matter if we aren’t using HTTPS or aren’t validating user input.
Read the blog article 7 Tips for Designing Secure REST APIs for more details about creating a secure REST API.
Wrapping It up
Designing a great REST API can be challenging because it requires a lot of upfront thought and design. I put together a RESTful API Design Cheat Sheet that includes many tips on designing a great client experience.
Also published on Medium.
