Skip to content

NDC Oslo 2025 Workshop: Designing APIs

With a year delay I could attend the workshop on Designing APIs by Irina Dominte (Scurtu). As we will soon be starting a major new API project, the timing of the workshop could not have been better.

Day 1: REST

The first day was all about REST. We started with the basics of "What is a resource?", revisited the definition of the REST architecture and talked about what parts usually fall off the wagon. We had a close look at HTTP status codes and learned how media types and custom headers can help us to transport more meaning with the responses our API sends. For versioning we talked about the options we have and the problems that happen when we put the version number into the URL.

After this theoretical block we could jump to the more interesting part and put all those topics into code. The errors and omissions in the code samples made this part harder than it needed to be. Nevertheless, we got everything sorted in the end and could implement the examples.

To finish day one, we made our API more resilient with the Microsoft.Extensions.Http.Resilience package. That package combines different approaches for retrying calls that we can attach to HTTPClient, what helps us when our API needs to call out to other services.

Day 2: gRPC and messaging

After we finished the part about resilience, we dived into the problems of REST. While not exclusively made for, REST APIs end up most often as a CRUD abstraction. When that is not what we need, a different approach could be a better fit.

The RPC (Remote Procedure Calls) protocol allows us to access services on different machines as if they were running locally. With gRPC we can use a modern open-source implementation that supports many programming languages. In gRPC we put our service definition (the interface or contract) into a *.proto file and the code generators of Visual Studio can create a client for us – the same way they do it with remote services (like WCF).

We could replace REST API calls downstream from our API into other internal systems with gRPC. While REST stays at the border to the outside world, gRPC could help at the internal side and speed things up with HTTP/2.

The final part of the workshop was messaging. We implemented a contract and used MassTransit to handle the whole configuration part for RabbitMQ. That way we could integrate messaging in no time. The outbox and inbox pattern was a solution we discussed to prevent ghost messages and zombie records. Instead of directly sending the messages, we write a note into a database table. That way we get transaction support in our database and a separate service sends the messages that we queued that way.

Important points to consider in your API

Among the many things we discussed in the workshop, I find these points the most important ones:

  • Conventions are there for a reason, do not fight against them. If you indeed need it differently, maybe you need to change the technology that you want to use.
  • Do not directly return the data as it is in the database – add an abstraction that can hide all the parts that are not needed by the consumers of the API. That way we gain flexibility, and the API does not need to change when we change how we store data.
  • Do not forget the fallacies of distributed computing – the network latency is not 0, bandwidth is finite and transport costs money.

Helpful resources

These tools and resources could prove to be useful:

Conclusion

The two-day workshop was intense and informative. We covered a lot of topics and had many opportunities to put the theoretical knowledge into practice.

The many errors in the script where we copied the code examples from were disappointing. We were there to learn about APIs and ended up fixing configuration problems of AutoMapper. One trial run through the examples would have found most of the problems in the code and many of the missing sentences. In this case the workshop did not deliver at the NDC quality level I am used to from the previous years.

The messaging part at the end of the workshop added a lot of complexity, but not much value. It felt out of place, reduced the time of the other two topics and would better be left out for further workshops. The time could be better spent on a practical exercise on versioning, testing, or API documentation.

Despite these points, I was able to benefit a lot from this workshop. But with just a few adjustments the experience could have been much better.