Creating Better Web APIs

Web APIs are the essence of the internet. They give developers the openness of the web and the ability to access any data on the internet. However, there are some best practices specific to APIs. The ability to select the right HTTP verb, how to document APIs, and testing APIs are just some of the topics we’ll cover.

With that said, the techniques covered in this chapter are vast and dense. We’ll try to pack as much information as possible to help build quality APIs. We’ll also provide relevant links for further research.

In this chapter, we’re going to cover the following main topics:

• Creating APIs quickly
• Designing APIs
• Testing Web APIs
• Standardized Web API techniques

In this chapter, we’ll learn how to design, create, test, and document APIs and how to perform full end-to-end tests of our APIs through a CI/CD pipeline.

We’ll finish this chapter by reviewing some of the more common...

Technical requirements

In .NET 8, Web APIs take a front seat. Visual Studio has added new features to make Web APIs easier to build and test. For this chapter, we recommend using Visual Studio 2022, but the only requirement to view the GitHub repository is a simple text editor.

The code for Chapter 09 is located in Packt Publishing’s GitHub repository, found at https://github.com/PacktPublishing/ASP.NET-Core-8-Best-Practices.

Creating APIs quickly

With .NET 8, APIs are integrated into the framework, making it easier to create, test, and document. In this section, we’ll learn a quick and easy way to create a minimal API using Visual Studio 2022 and walk through the code it generates. We’ll also learn why minimal APIs are the best approach to building REST-based services.

Using Visual Studio

One of the features of .NET 8 is the ability to create minimal REST APIs extremely fast. One way is to use the dotnet command-line tool and the other way is to use Visual Studio. To do so, follow these steps:

1. Open Visual Studio 2022 and create an ASP.NET Core Web API project.
2. After selecting the directory for the project, click Next.
3. Under the project options, make the following changes:
   • Uncheck the Use Controllers option to use minimal APIs
   • Check Enable OpenAPI support to include support for API documentation using Swagger:

Figure 9.1 – Options for...

Designing APIs

In this section, we’ll cover the best approach for delivering intuitive and clear APIs to our users. The design of an API should be well thought-out and make sense when a user wishes to make a request.

To create a truly REST-based API, we must use a different mindset. We have to think of ourselves as a user and not a developer. When writing APIs, the users of the API are fellow developers.

Disconnecting from existing schemas

When designing APIs, we need a user’s perspective as opposed to basing an API on a class hierarchy or database schema. While developers may consider creating an API based on a class hierarchy or database schema as a shortcut, it could create more complexity as to which resource to use when retrieving data. One example is using an Order resource to find a contact. While an Order entity in Entity Framework Core could contain a Company property and we need the contact of the company, we wouldn’t write https://www.myfakesite...

Testing Web APIs

Once we have our APIs designed and created, we need a way to test them in our IDE and our integration tests. Luckily, Visual Studio has added the new Endpoints Explorer.

In this section, we’ll learn two ways to test our APIs. One way is through our development environment using Visual Studio. The second way we’ll test our API is through integration tests. If we have a CI/CD pipeline (which we should from Chapter 2), these will automatically run to confirm our APIs work as expected.

Visual Studio Endpoints Explorer

Historically, developers using Visual Studio had to run a separate tool to test their APIs, but with the latest version of .NET 8, the Visual Studio team added a new panel called Endpoints Explorer:

Figure 9.4 – Endpoints Explorer

If we have a collection of APIs defined in the Program.cs file, our collection will appear as follows:

Figure 9.5 – Collection of APIs...

Standardized Web API techniques

In this section, we’ll learn how to use HTTP verbs and status codes properly, how to avoid large dependent resources, how to create paginations for APIs, how to version an API, using DTOs instead of entities, and the best way to make API calls from .NET.

Using the right HTTP verbs and status codes

So far, we’ve looked at how to use HTTP verbs and how to return status codes. While this may seem like a trivial thing, some systems ignore these standards and use POSTs all the time, regardless of the function.

Swagger provides a great template for documenting APIs and with Visual Studio’s new Endpoints Explorer, Visual Studio brings this fundamental documentation down to the developer’s IDE, making the API easier to read and implement in other projects, showing developers what verbs to use and what status codes are expected.

In our example of a shopping cart API earlier in this chapter, users were going to add products...

Summary

In this chapter, we learned about several techniques, such as how to design an API by disconnecting from technology by becoming a user of the application, identifying the resources, and using the right HTTP verbs and correct status codes. We also learned how to create, test, and document APIs, along with why minimal APIs are important. After, we learned how to use the new Endpoints Explorer in Visual Studio 2022, as well as how to build an automated end-to-end test of our APIs in a CI/CD pipeline.

Once we understood the process of writing APIs, we examined what standards were used in the industry to create common and useful APIs, such as using the correct HTTP verbs and status codes, avoiding large URLs, how to use pagination with APIs, versioning our API, using DTOs instead of entities, and the optimal way to use HttpClient when making API calls from .NET.

In the next chapter, we’ll look at how to improve performance across various topics we’ve covered...