Welcome to the next lesson in our course on creating a JSON API with Minimal APIs in ASP.NET Core. This lesson focuses on the importance of returning meaningful and structured error messages when things go wrong in an API. Not only does providing detailed error information enhance the usability of your API, but it also aids in debugging issues more effectively. We will explore the Problem Details Web Specification and learn how to implement it using the Problem and ValidationProblem methods provided by ASP.NET Core. Let's dive in!

The Problem Details Web Specification, defined in RFC 7807, standardizes how to represent error conditions in HTTP APIs. This specification ensures that error responses are consistent and provide all the necessary information to diagnose problems.

Here is an example of a JSON response following this specification:

JSON
Copy to clipboard
1{
2    "type": "https://httpstatuses.com/404",
3    "title": "Not Found",
4    "status": 404,
5    "detail": "Todo item not found",
6    "instance": "/todo/999"
7}

Explanation of the fields:

• type (optional): A URI reference that identifies the problem type. When dereferenced, it might provide human-readable documentation for the problem type.
• title (mandatory): A short, human-readable summary of the problem type. It should remain consistent for the same type of problem across different occurrences.
• status (mandatory): The HTTP status code generated by the origin server for this occurrence of the problem.
• detail (optional): A human-readable explanation specific to this occurrence of the problem.
• instance (optional): A URI reference that identifies the specific occurrence of the problem. It might be useful for linking to logs or other internal details about the occurrence.

By adhering to this structure, your API can communicate errors more effectively and consistently, aiding both developers and users in understanding and troubleshooting issues.

ASP.NET Core provides two helper methods that comply with the Problem Details Web Specification: Problem and ValidationProblem. Both of these methods return Problem Details JSON. These methods offer a structured way to return error details to the client.

• Problem: Used for general errors and returns a status code of 500 by default.
• ValidationProblem: Specifically designed for validation errors and returns a status code of 400.

Here’s how you can use the Results.Problem method in an API endpoint to return a structured error message:

C#
Copy to clipboard
1public IResult GetTodo(string id)
2{
3    return TodoItem.All.TryGetValue(id, out var todo)
4        ? Results.Ok(todo)
5        : Results.Problem(detail: "Todo item not found", title: "Not Found", statusCode: 404);
6}

The TryGetValue method checks if the Todo item exists; if it does, the item is retrieved. The Results.Ok(todo) method returns a 200 OK status along with the Todo item when it exists. If the item is not found, the Results.Problem method returns a 404 Not Found status with a detailed error message.

Let’s look at how to use the Results.ValidationProblem method to handle validation errors in an API:

C#
Copy to clipboard
1public IResult AddTodo(TodoItem todo)
2{
3    var id = Guid.NewGuid().ToString();
4    var newTodo = todo with { Id = id };
5    return TodoItem.All.TryAdd(id, newTodo)
6        ? Results.Created($"/todo/{id}", newTodo)
7        : Results.ValidationProblem(new Dictionary<string, string[]>
8          {
9              {"id", new[] {"A Todo item with this ID already exists"}}
10          });
11}

The Guid.NewGuid() method generates a unique ID for the new Todo item. The Results.ValidationProblem method returns a 400 Bad Request status with detailed validation error information if a Todo item with the same ID already exists.

In this lesson, you learned about the importance of returning detailed and structured error messages using the Problem Details Web Specification. You explored how ASP.NET Core provides the Problem and ValidationProblem methods to create standardized error responses. These tools help make your API more user-friendly and easier to debug. Happy coding!