I recently presented An Introduction to RESTful APIs as part of the vBrownBag’s API Zero to Hero series. The video is sort of long, but the meaty bits have been described in the show notes within the video’s description if you’re curious as to the high level details of using a RESTful API.

After this published, I received a question on Twitter to go deeper into querying an API.

Seems like a good topic to scratch!

Endpoint Parameter Types

It’s worth noting that there’s a few different ways to supply parameter data to an endpoint:

• Path
• Body
• Query

These types are used to help you understand where to place the parameters when using an API call. Before I get into Craig’s question, let’s brush up on the Path and Body types.

Path Parameter

The first one, Path, is something I briefly drilled through in the video. This type of parameter lives within the endpoint’s URI – which looks like a web address – to help scope the call down to one individual resource. This is nice because it prevents you from having to build a body just to supply something as simple as a resource identifier. I’ll use an example endpoint from Rubrik to dive deeper.

Below is an endpoint used to retrieve resource data on a VMware virtual machine that is known to the cluster. The endpoint is /vmware/vm/{id} with the {id} part being the body parameter that is required for the call.

When making the call, the URI would be something like /vmware/vm/VirtualMachine:::123456789 to let the API know which virtual machine you’re looking to investigate. You can see this in the OpenAPI spec when looking at parameter type in the bottom and the fact that something within the endpoint has curly braces around it – in this case, {vm}.

Body Parameter

The next parameter type, Body, indicates when you need to construct a body of data for the endpoint to inspect. This is sometimes referred to as a payload. You build a body in whatever format is desired by the API. In Rubrik’s case, the format should be JSON, but other APIs might use XML, YAML, or something else entirely. Most all endpoints that need a body parameter are looking to change the resource’s data.

In the example below, you can see another endpoint that allows you to change the resource data for a virtual machine. All of the parameters that can be changed are provided as body parameters.

The nice thing about the OpenAPI spec is that it also provides the model and example values for body parameters. This is shown in the bottom right corner. You can even click the box to have all default values transferred over to the value area.

With this endpoint, you’d supply both a path parameter – the {id} value of the virtual machine – and a body parameter – the JSON payload representing all of the values you wish to change for this particular virtual machine.

Query Parameter

Let’s get back to Craig’s question on using a Query parameter. These are special parameters that allow you to change the scope of the request to reflect a subset of resources. Put simply – you may want to retrieve data on a large number of resources, but wish to filter out some of the resources if they don’t match a name, type, size, state, or so forth.

Let’s return to the earlier example of getting details on a virtual machine. What if you don’t already know the virtual machine id value? In that case, you’d likely want to start by using the /vmware/vm endpoint to get a list of all known virtual machine details. But for larger systems, this might return tens of thousands of resources. Instead, let’s leverage a query!

If you look at the parameters section, you’ll see a few of the available queries (I ran out of screen space). Each one allows you to modify the URI to supply query information to the endpoint. This tells the endpoint to filter through the results and only return the ones that match one or more of the query values.

Constructing a query within the URI is pretty straight forward. To start, you’ll add a question mark (?) to the end of the endpoint to signify that query information is forthcoming. You then supply the parameter name and value in a name=value format. Additional parameters are separated with an ampersand (&).

Let’s look at a few examples below:

• /vmware/vm?is_relic=true sets the is_relic parameter to true and only returns resources that match this value.
• /vmware/vm?is_relic=true&sort_by=effectiveSlaDomainName sets the is_relic parameter to true as well as the sort_by parameter to effectiveSlaDomainName. Resources that match both of these will be returned.

And so forth. Much like the path parameter, the query parameter is nice because it’s just plopping data directly into the URI so that the endpoint knows what to do. I also find that most APIs ignore erroneous query parameters, so don’t assume you’ll generate a 4xx error if you supply a bogus parameter.

That’s it! Fairly simple stuff once you get the hang of it. Now, go forth and get RESTful! (that was super nerdy, I know)