How to design a RESTful API on AWS

Have you ever asked yourself what is a REST API? How do I design a RESTful API on AWS Cloud? How do I write a RESTful java microservice? As a software engineer building on AWS, I’ll walk you through designing a REST API.

What is a REST API?

A REST API is a way for clients to get/store information with an application through HTTP. This is typically what websites and mobile apps use to communicate with backends services. For example: What’s today’s weather in Paris? A website makes a HTTP call to a weather service with Paris as an input. In response, the weather service returns a message with the details that that website would need to show that information.

The text format that the client and the backend service exchange is usually in JSON structure. However, you could choose to use others like HTML, XML, plain text and so on. The RESTful specification does not define what format you must use unlike something like SOAP which uses XML.

REST APIs should also be stateless. When calling the same API multiple times, nothing is stored in the backend causing it to change its response. For example, with pagination, calling an API will return a “page” (or subset) of items. Every time i call it, it will return the same subset, regardless of if I had already called that API. However, if I call that API give me the next 20 items starting an index 40, it will then return something different.

Another characteristic of REST APIs is that they can be cached. When requesting the item, with an id of 123, multiple times, the first request would go to the microservice. The second time I request that item, with a short window, it is unlikely that it has changed. At that point I should instead just receive a cached response.

Business Use Case to Design a REST API for

So let’s put some of what we have learned to practice. We will be designing the APIs for the following business use case. An application needs a way to get the list of upcoming events. The consumers for this API could be a mobile application that displays the events that you are registered for. This API could also be used an a website that advertises upcoming events.

Designing the RESTful API

When you name an api you want to use something short and simple. It should accurately convey the service or data it is providing and indication of what you will receive. You don’t want to use long string like events-i-signed-up-for. Instead you want things like that to show up in an hierarchy of paths like events/search?registered=true.

The next thing you want is versioning. When creating an API, you define a contract with you consumers. When you need to make a breaking change, they may not be able to update their code base at the precise minute that you deploy. Instead, you would deploy a new version in addition to your existing version. This gives clients time to migration from the previous version to the new one. The key here is to not make breaking changes, but when you have to, use versioning.

A simple path could be as follows. The name of your microservice, the version number and then the resource that you are requesting. In the below example, the microservice is called events, the version is v1 and the resources are events and locations respectively.

https://api.mydomain.com/events/v1/events/
https://api.mydomain.com/events/v1/locations/

These APIs would return a list indicated by the plural resource in the path and brackets in the response

[
  {
    "id": 123
  },
  {
    "id": 234
  }
]

A path to return a specific event would be structured as follows. The name of your microservice, the version number, the resource that you are requesting and the id of the specific item you want.

https://api.mydomain.com/events/v1/events/{eventId}/
https://api.mydomain.com/events/v1/events/{eventId}/locations

You can also do complicated searching on resources with something like the below pattern. The path is the name of your microservice, the version number, the resources that you are searching, and that fields that should match the returned resources. For example in the below paths, it searches for events where the date is greater than 2021-07-01 and the status is CANCELLED. The second path searches for events that have a duration of longer than 1 hour

https://api.mydomain.com/events/v1/events/search?date[gt]=2021-07-01&status=CANCELLED
https://api.mydomain.com/events/v1/events/search?dateAndTime.duration.length[gt]=1&dateAndTime.duration.unit=HOUR

JSON Structure of our RESTful API

Now that we have an idea of what our paths should look like let us look at the JSON structure that our responses will look like. JSON objects are surrounded by curly braces {}. Then the contents are key value pairs where the keys are surrounded in quotes. The values can be the following data types: a number, a string, a boolean, an object, a list or simply null.

When choosing which data types to use you want to keep flexibility in mind. Considering that this is a contract with your clients, you want to choose data types that will allow you to extend. For example status is a property that would not need multiple fields. However, the location could be multiple places, so a list would allow us to represent that instead of having a flat structure like location1, location2, etc. Another example is date and time. It could have multiple attribute like time, date, and duration. This might be better represented with another JSON object.

{
   "status": "ACTIVE",
   "public": true,
   "id": 1234556,
   "title": "Weird Animal Facts",
   "description": "Tune in to learn about how horses make the neighing sound",
   "dateAndTime": {
     "date": "2021-06-30",
     "time": "08:00:00",
     "timeZone": "GMT",
     "duration": {
       "length":"1",
       "unit":"HOUR",
     }
   },
   "locations": [
     {
       "type": "ONLINE",
       "url": "https://ivonneroberts.com/meetingURL"
     },
     {
       "type": "VENUE",
       "address": {
         "streetAddress1": "1 5th Avenue",
         "streetAddress2": null,
         "city": "New York",
         "state": "NY",
         "zip": 10001
       }
     }
   ],
   "cost": {
     "currency": "USD",
     "price": 20,
     "unit": "PER_PERSON"
   }
 }

Conclusion

We now have walked through how I design a RESTful API, the path and JSON structure, on AWS Cloud. I continue to build on this design in How to Choose a Database on AWS. Check back weekly for new content. Feel free to comment below any questions you may have or reach out to me on twitter at @ivlo11

Happy Coding!