.NET Tools

.NET Annotated Monthly | April 2023

Did you know? JavaScript was released on December 4, 1995, after being quickly developed over 10 days, to work with the Netscape browser. It stuck around, became popular, and in 1997 folks finally recognized the need for formal structure and support, via ECMA. The rest is history as it has taken over the web.

.NET news

Featured content 

We’d like to thank Poornima Nayar for curating this month’s featured content! Poornima is a .NET developer with over 10 years of experience in .Net and Umbraco. She is a Microsoft MVP for Developer Technologies and an Umbraco MVP. Poornima is passionate about technology and enjoys sharing her knowledge with the wider tech communities. Outside work, Poornima is a mother and spends a lot of time with her daughter. Poornima is also a student of Carnatic Music, a stream of Indian Classical Music. Connect with Poornima on Twitter.

Thank you JetBrains for having me as an author, to write about one of my favourite topics – APIs! APIs or Application Programming Interfaces are everywhere! Talk about shopping online, booking a cab or getting a takeaway for your dinner on a Friday night – APIs are everywhere. They are software intermediaries that help establish communication between applications. When I think about building APIs in .NET, the terms that come to my mind are REST, GraphQL and gRPC. As of today, if you think about building APIs in .NET these are the options available to us. 

gRPC is a flavour of Remote Procedure Framework(RPC). We had WCF in the past, with .NET Framework for RPC requirements. gRPC started having out-of-the-box support in the modern .NET world from .NET 3.0 onwards. Microsoft recommends gRPC for your RPC requirements. gRPC is an open-source framework and is language-neutral, platform-neutral and extensible. And this is made possible using the magic that is Protocol Buffers. With gRPC, Protocol Buffers are used as the interface definition language as well as the message exchange format.

The contract of your API (service and procedures) is defined in a .proto file. The tooling available creates C# code for each proto file whereby each service is generated as an abstract class and the procedures in a service generated as virtual methods in the abstract class. You can give the various procedures your own implementation(by default, the generated virtual methods cannot be used until you give them an implementation) by inheriting from the abstract class and overriding the methods. 

gRPC is designed for HTTP/2 and the .NET implementation of gRPC was the first of its kind to come up with suggestions on how gRPC should work over HTTP/3. There is superior tooling available in the .NET world to help you develop gRPC APIs and you can make use of the out-of-the-box dotnet templates to get yourself started with gRPC. With .NET 7, a feature called gRPC JSON Transcoding was added to gRPC whereby you can extend your existing gRPC API to an HTTP API as well, without code duplication! gRPC is a perfect candidate for internal services, as microservices, for IOT devices and polyglot environments. 

gRPC services written in one language can be consumed by clients written in many other languages. To consume a gRPC service you need a gRPC Client. But fear not, the tooling has got it all covered for you. The .proto file together with the tooling can generate the client and stub methods for a wide variety of programming languages. Sharing the .proto file, or rather, making it available to the consumers to generate the client and stub methods is of prime importance here. 

Representational State Transfer (REST) is undoubtedly the most widely adopted and the most popular and successful API pattern out there. It was first mentioned in 2000 by Roy Fielding in his famous dissertation. He suggested it as an architectural pattern for distributed hypermedia systems like the Web. It is a set of guiding principles, known as the famous Fielding constraints. Any system that confirms these constraints can be termed as a RESTful system. It is not limited to just API at all. In fact, REST was proposal to standardise a hypermedia system like the web. We are bringing it to an API level. It is not a standard by any means, how you implement these constraints is totally up to you! 

With REST, everything is based on resources – collection of resources, modelling a resource and acting upon them. A resource can be anything that can have a computer readable format – a person, a vehicle, a fruit, anything! Resources have a unique identifier – a url in this instance. When you ask for information about a resource, the server gives you a representation of the resource that you just asked. This helps the client change the application state, stored on the client.

Similarly, to change a resource, the client can provide an updated representation of the resource that might lead to a change in the resource state on the server. This manipulation of application state and resource state using resource representations is the essence of REST and where it gets its name from. There is of course, out-of-the-box support for building REST APIs in the .NET world!

REST reuses the rich toolkit HTTP provides us with – HTTP Verbs, Status Codes, Headers, Requests, Responses, Caching. With a REST API a typical endpoint serves a set of resources for e.g. users. Getting a list of resources, a particular resource, creating, updating and deleting resources are made possible by issuing the appropriate HTTP Verb and headers to the endpoint.

Writing about REST cannot be complete without mentioning HATEOAS (Hypermedia as the Engine of Application State). HATEOAS is what completes REST. It is the factor that decouples your clients from the server and is the server’s answer to the question “What is the next step I should take?” asked by the client. Application state is stored on the client. Instead of relying upon hardcoded next course of action to change the application state on the client, it relies upon hypermedia included in the server response. Hypermedia drives the change in application state. This is the concept of HATEOAS.

Typically, every GET response from the server includes a set of hypermedia links describing the actions that can be performed on the resource as well as how to gather information about related resources. Without HATEOAS implemented, what you would be having is a HTTP API. Read more about Richardson Maturity Model to understand more about this concept!

REST is the most versatile API when it comes to client usage. Any app that can issue an HTTP request can consume a REST API. It excels as microservices and management (CRUD) APIs.

GraphQL is an API pattern which is very very unique. It is a query language for your API, supported by a server-side runtime that can parse, validate and execute these queries. GraphQL acts like an application layer. Your data could be in a database, coming from a REST API or even another GraphQL endpoint. It is essentially an interface between your consuming app and back-end hence GraphQL APIs can be termed GraphQL servers. GraphQL helps you visualise your data as a graph and makes it possible to extract parts of that graph, hence the name GraphQL. 

GraphQL is renowned as a client-focussed API. With gRPC and REST you have fixed requests and fixed responses. However, with GraphQL, you get a single endpoint that can take in any valid GraphQL query. The consuming app can issue any query depending upon their needs and the server replies back with a response that mirrors the query. The response structure is therefore predictable to the consuming developer. The response returned only contains what the client asked for – nothing more, nothing less.

Furthermore, the queries can be really flexible. The consuming app can query users and their friend details using a single query. In a typical REST world this would be at least 3 different API calls. In fact the very existence of GraphQL was to overcome this challenge REST posed. GraphQL is a specification. It is a blueprint that various implementations of this blueprint tries to confirm. There are many implementations of GraphQL across various different programming languages.

In the .NET world, there are 2 implementations of GraphQL – GraphQL.NET and HotChocolate. Both these implementations are open source. GraphQL, as a specification, is transport agnostic. Serving GraphQL over HTTP is the most popular choice. 

GraphQL supports 3 operations – query, mutation and subscription. Query is the root operation type for reading information. A mutation can be issued to mutate/change data. This covers inserts, updates and deletes. Subscription stands for real-time, pushed updates from the server. Clients can subscribe to real-time information from the server. All the 3 operations are performed over a HTTP POST. 

GraphQL is an experience-driven API. It is an ideal candidate for mobile apps where APIs need to cater in for flexibility. GraphQL is also useful in scenarios where you need data to be fetched from multiple sources. GraphQL can act like a gateway in such an instance.

If you wish to learn more on how these API patterns compare, watch my session REST, GraphQL and gRPC : A Comparison on the JetBrains YouTube Channel.

You are reading this newsletter thanks to an API! APIs are everywhere :-)

Programing tutorials and tips 

.NET tutorials and tips

Here’s a nice reference graphic to print and hang on your desk.


Related programming tutorials and tips:

Interesting and cool stuff

We all know a programmer like this. 🙈🙉🙊

And finally, the latest from JetBrains

⚒️ Check out our .NET Guide! Videos, tips, and tricks on .NET related topics. ⚒️

Blog posts, webinars, etc..

Don’t miss this fantastic offer! CODE Magazine is offering a free subscription to JetBrains customers. Get your copy today!

Sharing is caring! So share content that you find useful with other readers. Don’t keep it to yourself! Send us an email with your suggestions for publication in future newsletters!

Subscribe to .NET Annotated