In this post we are going to slip into Scott’s shoes – our “user” persona as discussed in the previous post.

Scott is primarily interested in being able to request catalog items, as well as interacting with items that he requested previously.

What you will need.

1. Open up the swagger docs at https://vra-fqdn/component-registry/services/docs
2. Navigate to the catalog-service using the drop down in the top right hand corner of the page.
3. Open Postman.

As mentioned in the previous post, authentication is the first thing that you should do within a session. Hence I won’t call it out explicitly below.

You may be wondering why I am referring to the catalog-service as the “Consumer API”. There are a number of administrative functions also available in the catalog-service – the Consumer functions are a subset of the catalog-service that don’t need special permissions to interact with.

Use Case 1: Requesting a Catalog Item

While there are a few different ways to request a Catalog Item via the API, but there is really only one way that you shoud request it.

1. Check what Catalog Items you are entitled to.
2. Check what the request body should be.
3. Check permissible values.
4. Submit your request.
5. Track the progress of your request.

Check what Catalog Items you are entitled to.

In your swagger docs, do a search for “entitled”. It should show up the following results. You may need to click on the “catalog” hyperlink at the bottom of the page to expand out the available URIs.

There are a two options there that sound like they could be viable:

1. /api/consumer/api/entitledCatalogItemViews
2. /api/consumer/api/entitledCatalogItems

Make note of the descriptions associated with each of these, and then find them in Postman. Execute them both and take a look at the results.

While both work, the first includes the hypermedia values required to both get the request template and to submit your request. Neat right?

Check what the request body should be.

This is pretty straightforward now – you already know the URI to get the request template because it was returned in the body of the previous request.

While this is a hyperlink, I don’t recommend clicking on it in Postman. This will open up a new request that is missing the headers you need in order to make a successful request.

There are a few ways around this – from within Postman, under the Headers tab, create a Preset. This will allow you to easily add a group of headers to a request. Alternatively, copy and paste the URI from the body of your previous request, and paste it into the address bar of Postman. Since you already have the headers defined this will work fine. Just don’t save the request!

Give it a go now, the result should look like the snipped result below.

Check permissible values.

Now that you have the body of your request, you could submit it using the “POST: Submit Request” link from Step 1. Doing so would submit your request with the default values. What happens if you want to change the defaults though? Do you simply keep guessing until you are within the bounds of permissible values? The good news is that you can check a request schema. These are specific to each catalog item, in the same way that the request template itself is specific to a given Catalog Item.

Search the swagger doc for “schema”.

The first result is https://{{vra-fqdn}}/api/consumer/entitledCatalogItems/{{id}}/requests/schema

You will need to enter the ID of the catalog item that you want to return the schema for. If it has value ranges, then you will see a result similar to the following:

This example shows memory, but the same data is available for other ranges.

Submit your request

At this point you have the request template, the permissible values that you can tweak should you choose to do so, and the URI to submit the request to.

Submit the request, and if all is well you will receive a 201 status code, and a body response that contains the below (and quite a bit more).

You should pay attention to line 3 “id”. This is the request id, and can be used to track the status of the request.

Track the progress of your request.

To find the API needed, switch over to the swagger docs and search for “requests”.

The one you are looking for is /catalog-service/api/consumer/requests

Using the id value from the previous request, submit the call and take a look at the response that comes back. The key called “STATE” tracks the progress, and you can check this as many times as you like until your request completes successfully.

Wrapping Up

Hopefully now you feel a bit more comfortable with making requests via the API. In the next post we will take a look at triggering Day 2 actions via the API.