Make a Product Details Request to the API

Table of Contents

Goals
Step by Step Guide

This tutorial will show you how to make a very simple product details API request to your provisioned demo instance of Broadleaf Microservices.

Tip	If you haven’t already, we recommend reading our introductory OpenAPI UI article before going through this.

Tip	While we believe the OpenAPI UI is the best way to experience the Broadleaf Microservices API, if you want to follow this tutorial using the popular Postman utility, please see our Postman Reference article before proceeding.

Goals

Using the OpenAPI UI, learn how to make a request to the Catalog Browse microservice to fetch product details.

Step by Step Guide

Note

There are actually two product details endpoints. One is in the Catalog Browse microservice at /product/details, and another is in the Catalog microservice at /product-details. The endpoint in the Catalog Browse service is a publicly available endpoint meant to be used for the storefront. Internally, it makes a request to the secured endpoint in the Catalog service to fetch the actual data (and combines it with other information like pricing).

This tutorial will show you how to make a request to the endpoint in the Catalog Browse service, serving as an example of making a request to a non-secured endpoint.

Navigate to the product details operation in the interactive OpenAPI UI.
1. Visit the OpenAPI UI (https://[your-demo-identifier].admin.blcdemo.com/api/docs).
2. Find the "Catalog Browse Service" the left navigation menu.
3. Scroll down to the "Product Details" tag.
4. Find the GET /products/details operation. This is the operation we will be making requests to.
Since this operation is publicly available and not secured, we don’t have to do anything for authentication/authorization. Onward!

Make a request to get details for the "Hoppin' Hot Sauce" product

As documented in the DetailsRequest parameter of the operation, the endpoint will need to be given either some product ID(s) or URI(s) to know which product(s) it needs to fetch details for. Since we want to keep things simple, let’s just get a single product ID.
1. To make this easy, we’ll visit the admin application and get a product ID from there.
  1. Sign into the Broadleaf Admin (https://[your-demo-identifier].admin.blcdemo.com) using the admin user credentials given to you upon signup.
  2. In the navigation menu, select "Products" under "Catalog". This should reveal a grid of products.
    
    Note
    Wondering where the product data came from? Your demo instance will have some simple seed data already populated at the time it is provisioned. These products come from that seed data.
  3. Click on the "Hoppin' Hot Sauce" product.
  4. From your browser’s address bar, grab the value after /products/, which is the ID of the product. In this case, it should be product4.

Build and send the request.

Return to the product details operation in the OpenAPI UI, and click the "Try it out" button near the top of the operation to enable drafting the request.

Specify request parameters.

The operation exposes quite a few parameters, but they’re largely optional. To keep things simple, we’ll just be customizing two parameters and leaving the rest as-is:

DetailsRequest - this object is actually separated into multiple query parameters (each property of the object becomes a separate parameter) at the time the request is made. The operation expects this data so it knows which products it needs to fetch information for. As you can see, the example value is sending productUris by default. However, we want to request by ID, so we will supply the productIds property instead, setting its value to an array with one element, "product4".

Note

Wondering how we knew there was a productIds property available? Since this operation is just an abstraction over a delegate operation in another service, it intentionally doesn’t have detailed schema information available. However, since we know the default delegate operation is GET /product-details in the Catalog service, we can look at the docs there to understand what we can supply. Navigate to the Catalog service specification, find the GET /product-details operation, and examine its parameters (particularly the productDetailsRequest parameter) to see what can be supplied. You’ll find the productIds and productUris properties there. Mystery solved!

X-Context-Request

X-Context-Request is a header containing crucial context information the server will use to "narrow" results. By default, the value for this is loaded from the "Application Context" example. We can’t just directly use this value, though, as we need to make sure it matches the context of your specific provisioned demo instance.

Change the applicationId property in the value to PD_[your-demo-identifier], where [your-demo-identifier] the unique identifier of your demo (ex: demo123abc). This is the applicationId of the application that was created when you provisioned your demo.

You can leave tenantId as-is, since your application will have been provisioned within that default tenant.

The UI should now look something like this:

Click the "Execute" button to submit the request.

Tip

Before submitting the request, open your browser’s developer tools to the "Network" tab. This will allow you to see the exact request that is made, which can be helpful in understanding how all of the headers (such as X-Context-Request and Authorization) and query string parameters were supplied. Some browsers even support "Copy as cURL" on requests, producing cURL commands that can be executed through a CLI or imported into software like Postman.

Examine the response.
1. If you scroll down a little, the "Server Response" will be shown. It should be a 200 with details about the "Hoppin' Hot Sauce" product
2. Well, we have the right response, but what does any of the data in the payload mean?
  1. You’ll need to see the response schema next to the 200 entry in the "Responses" section, as shown in the OpenAPI UI article.
    
    This gives you helpful conceptual information about the various fields you’d expect in the response and what they mean.
    
    In this particular case, however, the schema doesn’t fully capture the depth of all fields, especially those of the products themselves. As mentioned above, since this operation is just an abstraction over a delegate operation in another service, it intentionally doesn’t have detailed schema information available. Since we know the default delegate operation is GET /product-details in the Catalog service, we can navigate to the documentation of that operation to see the full detailed response schema. There, you’ll find the comprehensive corresponding schema ProductDetails:

This marks the end of this tutorial.

Tip	For extra credit, try making a request to fetch the product details of "Cool Cayenne Pepper Hot Sauce" using its URI!