Northwind Traders API Example – REST vs GraphQL

I wanted to try out a couple of different API technologies and see how they compared: REST API and GraphQL API.

I found a NET Core project dahlsailrunner/northwind-core-api that implements REST API, GraphQL, and gRPC endpoints against a Northwind Traders database.

Different API Technologies

REST API is probably more familiar to most where the HTTP actions of GET, POST, PUT, and DELETE are then mapped to CRUD actions on the backend.

GraphQL is less familiar where a query is set to the backend that is then interpreted and the a response is sent. It allows for a systems entities to be queried in a very similar way that a database is queried. GraphQL is also touted as having very fast, efficient, and typed return data.

gRPC is a Remote Procedure Call system that utilizes serialized calls to the backend for remote execution (being honest, I wasn’t really looking into this one.)

Northwind Traders Database

You don’t have to work with the Microsoft development stack for very long before you run into Microsoft’s infamous demo example database company, Northwind Traders.

Northwind Traders is a fictional company that is used for uncountable number of development examples for Microsoft development. It is used a lot when describing how to setup a complex relational database for enterprise applications. The database structure was created in 1997 and is now entering its third decade of use.

While the Northwind Traders database is available for Microsoft SQL Server, this project used a PostgreSQL version of the database that can be found here: dahlsailrunner/northwind_psql

Testing The Different API Technologies

As I stated, I was really interested in REST API and GraphQL. I am very familiar with REST as it is the basis of all API’s I have written in the past as well as the API technology that run’s all of Accutech’s APIs from Cheetah to ADEX.

I ended up not using the Docker setup for the Northwind database, and instead just created a new database on my local PostgreSQL 13 instance.

Once the database was setup, I could run the API project and start trying things out. When first launched, it takes you to a dashboard website.

Inside this one .NET Core web project is running the code for REST, GraphQL, and gRPC (though I didn’t try gRPC.)

Testing the REST API is easy enough as we can utilize the Swagger page to know how to make API calls into the project and then utilize Postman to make those calls. Below is an example of asking for the list of customers from the database.

Testing the GraphQL requires us to use the GraphQL Playground page where we can drop the example query that pulls back a list of customers (as seen below.)

On the surface it would appear that these two API endpoints are doing the same thing. But the way that the data is retrieved goes through two very different processes.

For the REST API, the GET call has a very defined contract. No parameters are sent, and no filters are made on the data. Basically it will always return all the customers.

Any filters, or limits, or add/remove fields would require the backend system to add that functionality. Multiple endpoints might be needed for the various ways that data is pulled from the system (i.e. GetCustomerById, GetLargeCustomers, GetOldestCustomer, etc…)

For GraphQL, the backend is setup as an interface between the data and the query be requested. The client now has control to filter, limit, or add/remove fields with its query to the API. Any changes happen on the client’s request, not in the backend system of the API.

Warning

The client doesn’t just have free access to an API’s data through querying. The GraphQL setup limits what is and isn’t available. But it doesn’t have to explicitly have to setup each query individually like a REST API would.

Arguments

Arguments can be added to limit the data in some way per a value. Below we have a customerId argument that will pull back the one customer matching the ID provided.

Conclusion

I only have a couple of hours to really dig into the example. I was able to implement the argument to pull by customerId which wasn’t a part of the demo project.

Here is a pretty good blog summarizing the GraphQL vs REST discussion: https://www.apollographql.com/blog/graphql-vs-rest-5d425123e34b/

Overall, I think that GraphQL is interesting and I think has one advantage over REST. That advantage is to define the data structure that comes back. The customer object has lots of fields, but by only querying the name and company name, you can cut down on the data over the wire whereas REST would return either the entire object or some pre-determined return model version.

I have recently been reading about an extension of the traditional MVC API setup of ApiController → Get, Post, Put, and Delete actions. This is the API EndPoint setup by Steve “Ard” Smith. You can read about API Endpoints on his blog at: https://ardalis.com/mvc-controllers-are-dinosaurs-embrace-api-endpoints/