Link

POST requests

We’ve explored the posts endpoint via the GET method. Let’s look at the same endpoint via the POST method by submitting some new data. In this demo, we’ll submit data from two different sources (Postman and curl). If you are following along with our demo container, and aren’t comfortable with one or the other, feel free to skip that section: your request count will be different, though there won’t be any significant impact.

In the last demo, the posts endpoint was documented via the GET method, and there aren’t any outstanding requests at this time.

alt-text

Let’s change that.

POST request with Postman

For this section, we’ll use Postman to craft a POST request with a JSON body. A tutorial of Postman is out of scope, though please note that for this demo we’ll need to specify the Content-Type header. We’ll be submitting a JSON body.

alt-text

Next, fill out the JSON body. We’ll want to submit a title and author. For this demo, we’ve added the following raw body:

{
	"title": "A new Postman post",
	"author": "Optic demo"
}

And click Send. We’ll see a status 201 (created) response, and the API feeds us back what we submitted as a JSON body.

alt-text

We can confirm that works in the Optic dashboard by refreshing the capture page. The /posts endpoint will appear, and the interactions, diffs, and undocumented endpoint counts will change. Don’t click on the endpoint yet. Let’s add one more request to this session.

alt-text

POST request with curl

Open a terminal, and send a request to the Optic proxy via curl (or your command line request tool of choice). In this example, we’ve abbreviated the title and author to save some typing. You may copy-paste the command, and save even more typing:

curl -d '{"title": "new post", "author": "Optic"}' -H 'Content-Type: application/json' -X POST http://localhost:4000/posts

The API will respond with your new post record as JSON in the body. Your ID may be different if you skipped the Postman section.

alt-text

Documenting POST requests through the /posts endpoint

After submitting two post requests, we’ll have two new interactions and diffs. As they both used the /posts route via the POST method, we’ll see one new undocumented endpoint. Note the 4 in the green bubble at the right side of the undocumented endpoint. This indicates the number of new requests to review. It sums up all requests and responses of interest, which is why it reports 4 items for 2 interactions.

alt-text

Click through the /posts endpoint, and click Next on the first modal dialog. Add a description such as Create a new post. Accepts author, title as JSON in request body and click Finish.

On the diff review summary, you’ll see a fully documented Request, with an example payload on the left and the documented shape on the right. Remember, the shape information will be used to generate the documentation.

alt-text

Likewise, the responses were also captured. The response returns the id field, an automatically incremented number determined by the server. We see the id value here is 2, and the shape shows up as a Number.

alt-text

If you have attempted two POST interactions, you’ll notice the additional observed request is under the second page in both the Requests and Responses sections. The values on the left will change, though the documented shape on the right will be the same as the first interaction.

alt-text

Click Document (2) bodies, and then click Commit changes to commit this documentation in Optic. There should now be no undocumented endpoints on the capture page in the Optic dashboard.

Viewing the POST documentation

Click the Document button on the bottom of the left navigation bar. The documented /posts endpoint shows up with the POST method.

alt-text

As before, you can click through the Full documentation for the POST method and see the shape of a request and a response. The documentation does not reveal any observed values, just the shape of the data. Note the response status code observed during capture is also shown, in this case 201 for a created record.

alt-text

alt-text

Next steps

We’ve seen different methods run against static paths. If there are changes to the previously documented requests or responses, Optic will capture these as well. Since they’re not new, Optic will generate a diff for review to highlight changes in behavior. Follow along the Changing Shapes demo to see this in action. Or, if you’re ready to try Optic on your own API project, check out our installation instructions to get set up in your local environment.