How to Choose the Right Technology for Web API in Your Application

February 09 2023

In modern software development, microservice architecture is a very popular choice for a good reason. This architectural pattern allows the building of large, complex systems by breaking them down into smaller, self-contained units called microservices. Each microservice is responsible for a specific function and communicates with other microservices through APIs. This approach has many benefits, such as increased flexibility, scalability, and ease of deployment.

Web APIs play a crucial role in microservices architecture by providing a way for services to communicate with each other over the internet or intranet and enabling loose coupling, flexibility, and integration with external systems. Web APIs have many functions, but in this blog post, we will specifically look at the Web APIs that provide access to the data.

In a microservices architecture, each service may have its own data storage, and the Web API is the means for other services to access this data. The Web API acts as a bridge between the data storage and the services that need to access it, providing a consistent and secure way for services to access the data they need.

Additionally, the Web API can also handle tasks such as data validation, data transformation, and data caching, which are essential for maintaining data consistency and performance. The use of Web APIs for data access also allows for easy integration with external systems, as well as simple scalability, by allowing different services to access the data they require without having to connect to the data storage directly.

Ready to Try ActiveReportsJS? Download a Free Trial Today!

Data Formats and API Styles

To exchange the data, a web API and its consumers should agree on the format in which the data are presented. The most common data formats are JSON and XML. JSON is a lightweight data-interchange format that is easy for humans to read and write and for machines to parse and generate. It is also less verbose than XML, making it a more efficient choice for data transfer.

XML, on the other hand, is a markup language that is more suitable for structured data, such as that used in documents. XML is also more self-describing, making it easier to understand the structure of the data. Let's compare a "Product" record obtained from the well-known "Northwind" database and serialized into JSON and XML formats:

{
    "ProductID": 1,
    "ProductName": "Chai",
    "SupplierID": 1,
    "CategoryID": 1,
    "QuantityPerUnit": "10 boxes x 20 bags",
    "UnitPrice": 18.0000,
    "UnitsInStock": 39,
    "UnitsOnOrder": 0,
    "ReorderLevel": 10,
    "Discontinued": false
}

<Product>
    <ProductID>1</ProductID>
    <ProductName>Chai</ProductName>
    <SupplierID>1</SupplierID>
    <CategoryID>1</CategoryID>
    <QuantityPerUnit>10 boxes x 20 bags</QuantityPerUnit>
    <UnitPrice>18.0000</UnitPrice>
    <UnitsInStock>39</UnitsInStock>
    <UnitsOnOrder>0</UnitsOnOrder>
    <ReorderLevel>10</ReorderLevel>
    <Discontinued>false</Discontinued>
</Product>

Other data formats, such as CSV and Protocol Buffers, are also used, depending on the specific use case and requirements of the application. The choice of data format will depend on the requirements of the application and the systems it needs to integrate with.

In addition to the data format, the web API and its consumers should agree on the method to request and modify the data. Several approaches can be used to interact with a web API, including Representational State Transfer (REST), OData, and GraphQL. Next, we will look at each style in detail.

RESTful API

REST is a widely used architectural style for building web APIs. It is based on the principles of HTTP and the principles of resource-oriented architecture. RESTful APIs use standard HTTP methods to perform operations on resources. The following are the most commonly used HTTP methods:

GET: Retrieves information about a resource. This method is used to retrieve data from a server without modifying it.
POST: Creates a new resource. This method is used to send data to a server to create a new resource.
PUT: Updates an existing resource. This method is used to send data to a server to update an existing resource.
DELETE: Deletes a resource. This method is used to delete a resource from a server.
PATCH: partially updates a resource. This method is used to send data to a server to update a specific part of a resource.

These methods are usually associated with a specific URI that identifies the resource being operated on. For example, the GrapeCity Demo Data Northwind API supports the following GET requests for the Product entity:

GET /northwind/api/v1/Products retrieves a list of all products
GET /northwind/api/v1/Products/{id} retrieves information about a specific product
GET /northwind/api/v1/Products/{id}/Category retrieves information about the category of a specific product

Additionally, some APIs also use other HTTP methods like HEAD, OPTIONS, and CONNECT, which have specific use cases in RESTful APIs.

It's worth noting that RESTful APIs use these methods in a standard and consistent manner, which makes them easy to understand and use. This is one of the reasons why REST is a popular architectural style for building web APIs.

OData API

OData (Open Data Protocol) is a web protocol for querying and updating data. It is built on top of the REST architectural style and is an open standard for creating and consuming data APIs. OData provides a way to represent and access data using a simple, standardized query language. It also supports advanced features such as batching and change tracking, making it a great choice for building APIs for complex systems.

OData APIs are based on the entity-relationship model, where entities are represented as resources and are identified by URIs. The resources can be queried and modified using standard HTTP methods like GET, POST, PUT, DELETE, and PATCH. OData defines a set of query options that can be used to filter, sort, and paginate the data. These options are passed as query parameters in the URI.

For example, the GrapeCity Demo Northwind OData API accepts requests that allow selecting Product entities applying filtering and sorting:

/northwind/odata/v1/Products?$orderby=productName&$filter=CategoryId+eq+1

OData also supports advanced features like:

Server-driven paging: allows the client to retrieve only the data it needs, reducing the amount of data that needs to be transferred.
Batching: allows multiple operations to be sent to the server in a single request, reducing the number of round trips between the client and the server.
Change tracking: allows the client to receive notifications when the data changes on the server.

OData is widely adopted. It's supported by many platforms, frameworks, and programming languages, which makes it a great choice for building APIs for complex systems. SharePoint, Dynamics CRM, and SAP are examples of systems that support OData.

GraphQL API

GraphQL is a query language and runtime for building and accessing APIs. It was developed by Facebook and is now an open-source technology. GraphQL provides a way for clients to specify exactly what data they need from a server rather than having to retrieve a fixed set of data. This eliminates the need for multiple endpoints and reduces the amount of data that needs to be sent over the wire.

In GraphQL, the client defines the structure of the data it needs in a query, and the server returns only the requested data. The client can also specify the fields it wants to retrieve, and the server will return only those fields. This allows for more efficient data retrieval, as the client only receives the needed data.

For example, the GrapeCity Demo Northwind GraphQL API supports queries like the following:

{
  orderdetails {
    product {
      productId
      productName
      category {
        categoryId
        categoryName
      }
    }
    quantity
    unitPrice
    discount
  }
}

The result is the list of all order details, including information about the ordered product and its category.

GraphQL also provides a way to define the data's structure through a type system. This allows the client and server to agree on the data structure and provides a way to validate the data before it is returned.

GraphQL also supports real-time updates through the use of subscriptions. This allows the client to subscribe to specific events and receive updates in real-time, making it a great choice for building real-time applications.

Reporting Microservices

A reporting microservice is a microservice responsible for producing visual reports based on the data retrieved by other microservices. This microservice would typically have two main features:

Data retrieval: The microservice would use web APIs to access the data from other microservices. This data would be used to generate the reports.
Report generation: The microservice would use a reporting library or tool to generate the visual reports. This could include things like charts, tables, and maps.

When you consider a reporting tool for your microservices, it must support the data format and data protocol that is used to exchange data between the microservices. The reporting tool should be able to easily connect to the web API and retrieve the data in the format it is presented. This will ensure that the reporting tool can easily and efficiently access the data it needs to generate the reports.

ActiveReportsJS is a 100% client-side reporting solution that supports Restful, OData, GraphQL, and other APIs. This makes it a great choice for building reports for microservices architecture, as it can easily access data from multiple services. It allows for the creation of highly interactive and customizable reports using a wide range of data visualization options such as charts, tables, and maps.

ActiveReportsJS is compatible with JSON format, which is widely used in web development, making it easy to work with data from various services.

You can check ActiveReportsJS demos at /activereportsjs/demos to look at the product capabilities in more detail.

Ready to Try ActiveReportsJS? Download a Free Trial Today!