RPC — REST — GraphQL API PROTOCOLS

There are different types of API protocols. Each of these are using for various approaches differ. Generally, to pick right API paradigm is not easy because there is no only one suitable protocol. First step should be domain researching and try to determine of controller methods.

In Example, lets build API for a book store and try to implement these API protocols.

Domain Methods:

· Get All Books

· Create Book

· Delete Book

· Get All Books from Writer

· Get All Books from Published Year

· Get All Writer

· Get Writer from Book Barcode

· Get Books from barcode or writer

Controller List:

· Book Controller

· Writer Controller

RPC (Remote Procedure Call) Protocol

RPC is the earliest protocol and basically it should look like a method. The developer should think method written in javascript. RPC Endpoints should explain what its purpose by name.

There are different of RPC endpoint styles. For example, some famous APIs is using dot or colon for separate action name and procedure name.

• Domain/controllerName.ActionName
• Domain/controllerName:ActionName

But it is not necessary to use dot or colon all the time. It is related by what is your convention.

Endpoints may look like that

• Domain/controllerName/ActionName

Let build Book Store Web API with RPC which are researched above.

• Get All Books

Domain/books/all

• Create Book

Domain/books/create

• Delete Book

Domain/books/delete

• Get All Books from Writer

Domain/books/byWriterId?writerId=1

• Get All Books from Published Year

Domain/books/byPublishedYear?year=2019

• Get All Writer

Domain/writers/all

• Get Writer from Book Barcode

Domain/writers/byBookBarcode?barcode= barcode

• Get Books from barcode or writer

Domain/books/byCriteria?criteria=writerIdORbarcode

There is a point here. When filter books by barcode, books controller is looks suitable but if filter books by barcode or writer id writer controller and book controller looks suitable.

How should decide suitable controller?

Now, decided conventions are important. Here, if both controllers are suitable for operation, select controller with same return type. In this example API return list of books so suitable controller is book controller.

This decision is not come from certain rule, it is just our convention we prepared before. It may change according to API developer.

REST (Representational State Transfer) Protocol

Rest protocol is much more common and it is very effective if API methods make CRUD operations only. According to REST conventions, next available action comes after related resources.

There are some differences between RPC and REST. One is URL path looks different. REST Convention is not need to method name. The operation duty may guess from action type like post, get, put, delete.

Next difference is response object styles. RPC returns only job result. Otherwise REST Protocols return data with related data. Therefore, API respond objects are very useful to select correct API protocol.

Let build same Book store API with REST protocol.

• Get All Books (GET Action)

Domain/books

• Create Book (POST Action)

Domain/books

• Delete Book (DELETE Action)

Domain/books/1

• Get All Books from Writer (GET Action)

Domain/writers/1/books

• Get All Books from Published Year

Domain/books?year=2019

• Get All Writer

Domain/writers

• Get Writer from Book Barcode

Domain/books/barcode/writers

• Get Books from barcode or writer

Domain/books?criteria=writerIdORbarcode

According to REST API, CRUD operations are standard. But Filter process is different.

• Domain/resources/resourceId/relatedData/relatedDataId?

It is how should REST API looks like.

In this API, Book controller can return writers. If API protocol selected as a REST, consider of what is the main data.

The main reason of use book controller when try to get writer from book barcode is filter property. Filter property which is barcode belong to product domain. That is why product controller is suitable for this operation. This API method will return writers but it is not important to decide controller.

GraphQL

GraphQL is the novel protocol and it is called as a query language. It is looks like RPC conventions but difference is response object is generating frontend. REST or RPC protocols response objects are preparing in backend.

Frontend request specific fields from server and server return only requested data with requested formats.

Get All Book Example:

• GraphQL Request

{
   books: {
     name
     writer {
       name
     }
  }
}

• GraphQL Response

{
  book: [{
      name: “The Clean Coder”
      writers {
        name: “Robert C. Martin”
      }
  },
  {
    name: “Database Management Systems”
     writers: [{
        name: “Raghu Ramakrishnan”
      },
      {
        name: “Johannes Gehrke”
      }]
   }]
}