6 Creating resources

In previous chapters you learned a little about using Postman, and in one of those examples you learned how to create new reviews in the FarmStall API by executing a POST operation with a request body. Creating reviews is a critical part of this API—what good is a review-centric API without the ability to create reviews!

In this chapter we’ll describe how to create new reviews using POST /reviews. In addition to that, we’ll take a look at GET /reviews/{reviewId}. This GET operation interests us for two reasons: first, we’ll want to confirm that we did indeed create a new review by fetching the same review back again, and, second, we will see how a path parameter works (see figure 6.1). Part of the charm of this approach is using the API itself to verify our work.

Like response bodies, request bodies are described using OpenAPI’s JSON Schema variant and they require a media type to indicate the type of data being sent (application/json).

6.1 The problem

Right, let’s get set up to create reviews. We’re going to look at POST /reviews first. To describe it, we’ll need to know the details of the operation, including both the request and response.

6.2 Describing POST /reviews with a request body

6.2.1 Where to find request bodies

6.2.2 Describing the schema for POST /reviews requestBody

6.3 Executing operations with request bodies

6.3.1 Adding examples to make try-it-out look pretty

6.4 Describing GET /reviews/{reviewId} with a path parameter

6.4.1 Path parameters

Summary