Why RESTful API

api
software-architecture

REST is a widely used design style for developing APIs.

Author

Richard Ding

Published

March 22, 2023

Modified

December 2, 2023

Introduction

Application programming interfaces (APIs) are ways that applications communicate to each other through a standard structure or design. There are several design styles available for building APIs, including Representational State Transfer (REST), Simple Object Access Protocol (SOAP), and GraphQL.

Decision

We will use the REST architectural style for implementing the communication protocol between our client and server components, instead of SOAP or GraphQL.

Alternatives

SOAP

SOAP is a widely used technology for implementing web services. SOAP is based on the XML protocol and supports a wide range of messaging formats, such as binary and MIME types, making it quite flexible.

However, SOAP is fairly complex and heavyweight, which can make it more difficult to implement and maintain. SOAP requires a lot of additional metadata and processing overhead, which can result in slower performance and higher resource consumption. SOAP can also be difficult to debug and test due to its complexity and lack of visibility in the underlying communication logs.

GraphQL

GraphQL is an increasingly popular technology for building web APIs. GraphQL allows for very fine-grained control over what data is requested and given, so it offers the most flexibility. However, GraphQL can be complex to set up and maintain, especially for simple use cases. GraphQL can be integrated with REST API, which is a useful feature especially when handling large and/or complex requests. So if needed, we could incorporate GraphQL into existing REST API.

Reasons for the decision

These are the reasons we are deciding on REST:

  • Is lightweight and easy to implement, making it a popular choice for web-based applications.
  • Uses a simple and intuitive set of HTTP methods, which makes it easy for developers to understand and use.
  • Provides a clear separation of responsibilities between the client and server components, making it easier to develop, test, and deploy each component independently.
  • Follows a conceptually simple and traditional approach where the client sends a request to the server, and the server responds with the requested data.
  • Is often simpler to implement and offers better caching mechanisms.
  • Has better tooling support and is more widely adopted.

Conclusion

We believe that the simplicity, flexibility, and scalability of REST make it a better choice for the client-server communication needs of Seedcase.