Learn how to serialize the model for a POST action to an ION form, and return the form metadata to the client.
- [Instructor] We've built a route that allows the client to create a new booking in the hotel. The JSON body the client sends over the wire is bound to the booking form class. However, there's no way for the client to know what field should be submitted in the first place. To solve this problem, and make the API truly comply with the HATEOAS constraint, we can generate some metadata about the form and send that to the client. The goal is to return this ion form. We'll return a named form called book which includes an href to the route the client needs to submit to in order to create the booking.
The form also specifies that you should use the post method to interact with this route. Because we're creating a resource here, we'll send the create-form link relation. The value element of the form contains a collection of all of the form field elements. Each one of the form fields that needs to be submitted with this form is included in this value element. For each form field, all of the properties about the field are included, such as the name, what label should be displayed in the ui, if any, whether the field is required, what type it is, and so on. We can generate all of this data automatically using reflection and then send it back to the client.
I've added some classes to the project, which you can find in the begin state of the exercise files for this video. If you're following along, you can copy these new classes into your project or just open up this solution file and continue from here. In the models folder, I added a form model, which is simply a collection of form field objects. Each form field object has a number of properties that describe the metadata about the field. I've also added a class called form metadata in the infrastructure folder. This class contains a number of methods we'll use to generate the form metadata using reflection.
Alright, let's pull these pieces together and return the form to the client. We want this form to be attached to the room model, so let's open up the room model and add a property. We'll add a property of type form, called book. To make sure every room resource returned to the client includes this book form, we'll add it to the mapping profile. This way, any time a room resource is returned to the client, it'll include the form. Whether it's returned as a single resource or as part of a collection. In the mapping profile class, I'll add this member to the mapping between room entity and room.
I'll need to say form member, on the destination type, the book property, and we'll map that from the source by accessing the form metadata, class, and calling the from model method. We'll pass out a new instance of booking form which is the model we want to serialize. I added another helper method to the link class called to form. That should make this easy. You can find it in the link class, and you can copy that from the exercise files for this video. We can call link dot to form and then pass the route name, which is on the rooms controller create booking for room Async.
We need to pass the route values, which is the room id, and then we also need to specify that we want to use the post method, And we also want the create relation on this link. Alright, let's go ahead and test this out and see what we get in the response. I'm going to request the rooms collection from the API. We should see on each room resource a form attached, called book. I'll open up a specific resource so we can look at that by itself.
On this room resource, we can see the form named book. The href points to the correct route with the room's id included. The metadata about the to form fields is included in the value array. If we switch back to the collection response, we can see that each one of the room resources has its own form with a proper url. Now the client can dynamically discover and understand how to create a booking, simply by examining the API response. This approach can be reused with any route in the API that needs to express this type of form metadata to the client.
- REST vs. RPC
- Using HTTP methods (aka verbs)
- Returning JSON
- Creating a new API project
- Building a root controller
- Routing to controllers with templates
- Requiring HTTPS for security
- Creating resources and data models
- Returning data and resources from a controller
- Representing links (HREFs)
- Representing collections
- Sorting and searching collections
- Creating forms
- Caching and compression
- Authentication and authorization for RESTful APIs