Conceptual examples– REST APIs

Conceptually, say that we are building a web application allowing people to register for events. We explore two use cases next.

Registering for an activity

The first scenario we are exploring is a user registering for an activity. An activity is a sort of event in the system. We use an external payment gateway, so our application never handles financial data. Nevertheless, we must send transaction data to our backend to associate and complete the payment. The following diagram depicts the workflow:

 Figure 4.3: The DTOs implicated in an activity registration flow. 

The body of the request could look like the following JSON snippet:

{
    “registrant”: {
        “firstname”: “John”,
        “lastname”: “Doe”
    },
    “activity”: {
        “id”: 123,
        “seats”: 2
    },
    “payment”: {
        “nonce”: “abc123”
    }
}

Next, the following JSON snippet could represent the body of the response:

{
    “status”: “Success”,
    “numberOfSeats”: 2,
    “activityId”: 123,
    “activityDate”: “2023-06-03T20:00:00”
}

Of course, this is a very lightweight version of a registration system. The objective is to show that:

1. Three entities came in as an HTTP POST request (a registrant, an activity, and payment information).
2. The system executed some business logic to register the person to the activity and to complete the financial transaction.
3. The API returned mixed information to the client.

This pattern is handy to input and output only what you need. If you are designing the user interface that consumes the API, outputting a well-thought DTO can ensure that the UI renders the next screen just by reading the response from the server, saving your UI to fetch more data, speeding up the process, and improving the user experience.

We explore fetching information about an activity registration next.

Fetching activity registration details

In the same system, the user wants to review the details of an activity he registered using the preceding process. In this case, the flow goes like this:

1. The client sends the registration identifier over a GET request.
2. The system fetches the registrant information, the activity information, and the number of seats the user reserved for that activity.
3. The server returns the data to the client.

The following diagram visually represents the use case:

 Figure 4.4: The DTOs implicated in fetching the info related to a registered activity. 

In this case, the input would be part of the URL, like /registrations/123. The output would be part of the response body, and could look like the following:

{
    “registrant”: {
        “firstname”: “John”,
        “lastname”: “Doe”
    },
    “activity”: {
        “id”: 123,
        “name”: “Super Cool Show”,
        “date”: “2023-06-03T20:00:00”
    },
    “numberOfSeats”: 2
}

By creating that endpoint using a well-crafted output DTO, we condensed three HTTP requests into one: the registrant, the activity, and the registration (number of seats). This powerful technique applies to any technology, not just ASP.NET Core, and allows us to design APIs without connecting clients directly to our data (loose coupling).