Designing Your First REST API – Part 1

This article will cover the most common concepts of REST APIs writing an API definition using Swagger. Then, you can convert that definition into code using a language you prefer.

Please note that you require basic knowledge of HTTP and APIs.

You may also like:  Get Plenty of REST: REST API Tutorials

What Is REST?

REST stands for REpresentational State Transfer. This is an architectural style for designing APIs; it provides a set of standards that makes it easier for systems to communicate with each other.

REST was defined by Roy Fielding, a computer scientist. He presented the REST principles in his Ph.D. dissertation in 2000.

There are multiple advantages of using REST that have made this architectural style THE Internet standard for APIs.

1. REST-based interactions happen using HTTP.
   • This makes it easier for anyone to use REST without a learning curve since HTTP is known widely
2. REST is language independent.
   • We can implement REST APIs using any language we prefer. In fact, there are many tools that can automatically generate code skeletons when the API definition is provided.
3. Properly designed REST API is self-explanatory.
   • The REST concept is designed to have this behavior in an API. When we look at a properly designed REST API, we can understand what each resource path does without reading the documentation.

REST Concepts

There are a few concepts that we need to understand in order to move forward with REST APIs.

Resources

A resource is a data object that we need to modify using a REST API. These resource objects often contain a type, associated data, relationships to other resources, and a set of methods that operate on it. It is similar to an object instance in an object-oriented programming language, with a difference that only a few standard methods are defined.

Paths

Each resource in a REST API has a defined path that can be used to do operations on that resource. In most cases, this is a concatenation of the base path of the API and the resource name.

Request/Response Headers

Extra information sent to the server and back to specify the type of request/response, encoding, and content type, customized parameters, etc.

Response Codes

These codes return with the response and signify the status of the request sent to the server. Standard HTTP response codes are used.

REST Operations

REST APIs are defined using standard operations in HTTP.

GET returns a response, POST creates a resource, PUT updates a resource, and DELETE deletes a resource.

REST Principles

Stateless

• Stateless means the server does not remember anything about the user who uses the API. Each individual request contains all the information the server needs to perform the request and return a response, regardless of other requests made by the same API user.
• And also the response should contain enough information for the client to understand the data sent.

Uniform Interface

• Every resource in the server should have only one logical URI and should expose methods to access this resource.
• Paths in the API should follow standard naming conventions.
• All resources should be accessed using a common approach. This enhances the visibility of web interfaces.

Client-Server Separation

• The client and the server implementation should be independent.
• Both should be able to scale and evolve independently of each other.
• The client should only know the URI of a resource on the server and nothing else.
• The server should return the appropriate response based on a received request from the client.

Layered System

• The web service should follow the layered approach, i.e., we should divide our web service into different layers that cannot see beyond their immediate layer. E.g. authentication layer, data access layer, message processor layer, etc.
• Although, those layers should not affect the request or the response. The client should not know about how many layers if any, there are between the client and the actual server responding to the request.

Cacheable

• The server should send information about whether or not the data is cacheable, in a response. If the data is cacheable, it might contain some sort of version number.

An API Example

Let’s look at defining our own simple REST API. To understand the REST concepts easily, I’m considering a simple scenario of an online bookstore. The main resource we need to expose through our new REST API is books. A book object has several attributes such as a unique id, a name, an author, and a price. And also a single book can have multiple reviews.

{
    "id": "B10001",
    "name": "The Adventures of Tom Sawyer",
    "author": "Mark Twain",
    "price": "$4.90",
    "reviews": [
        {  
            "id": "R1001234",
            "score": 4.3,
            "comment": "Good book to read.",
            "user": "vihanga"
        }
        ...
    ]
}

Accordingly, we can consider reviews as another resource in our API, which exists inside books resource.

Now, let’s see what APIs we can define to consume these two resources.

APIs for Books Resources

• GET https://mybookstore.com/api/books/
• Return all book objects.
• POST https://mybookstore.com/api/books/
  • Create a new book in the system.
• PUT https://mybookstore.com/api/books/{book-id}
  • Replace the content of the book object identified by the book-id.
• DELETE https://mybookstore.com/api/books/{book-id}
  • Delete the book object identified by the book-id.

APIs for Reviews Resources

• GET https://mybookstore.com/api/books/{book-id}/reviews
  • Return all reviews of the book object, identified by the book-id.
• POST https://mybookstore.com/api/books/{book-id}/reviews
  • Create a new review for the book object, identified by the book-id.
• PUT https://mybookstore.com/api/books/{book-id}/reviews/{review-id}
  • Replace the review identified by the review-id, of the book object identified by the book-id.
• DELETE https://mybookstore.com/api/books/{book-id}/reviews/{review-id}
  • Delete the review identified by the review-id, of the book object identified by the book-id

Notice that all paths for the reviews resources are defined under a specific book resource identified by the book-id. That’s because according to our business case, a review cannot exists without a book.

Now that we know the basic structure of the REST API we’re going to create, we can start defining fine-grained details of each path such as how the request body should be sent, what kind of response object would be returned, what error codes could be possibly sent, etc. For this purpose, we can use many tools that are available freely on the Internet. I prefer to use SwaggerHub. You can create an account for free.

I will explain that information in detail with my next post.

I hope you got an understanding of the basics of REST. Do comment if you have any questions.

Cheers!

Further Reading

REST API: Your Guide to Getting Started Quickly

Foundations of RESTful Architecture