Why RESTful API

api
software-architecture

REST is a widely used design style for developing APIs.

Published

March 22, 2023

Context and Problem Statement

Application programming interfaces (APIs) are ways that applications communicate to each other through a standard structure or design. It is important for a project like Seedcase to chose an API format early on, bearing in mind both what will work best for the application but also which resources there are available within the team. The question the becomes:

Which API technology will best serve the needs of the Seedcase project?

Decision Drivers

Considered Options

There are several design styles available for building APIs, including Representational State Transfer (REST), Simple Object Access Protocol (SOAP), and GraphQL. We have looked at REST, SOAP, and GraphQL as possible API tech for Seedcase.

REST

Benefits

  • 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

Drawbacks

  • Item 1

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.

Benefits

  • Based on XML
  • Supports a number of messaging formats making it flexible

Drawbacks

  • Complex to implement
  • Requires additional metadata and processing overhead
    • can result in slower performance and higher resource consumption
  • 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. 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.

Benefits

  • Control over what is transmitted i very detailed
  • Flexible
  • Can be integrated into REST API

Drawbacks

  • Complex to set up and maintain

Decision Outcome

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

Consequences