Using the API Explorer

This guide describes how to use the API Explorer to try out Monitoring API methods. API Explorer is a widget attached to the REST API reference page for a method. It appears as a panel with the title Try this API. The following screenshot shows the panel as it appears for a method with only one parameter, name:

The API Explorer widget

The API Explorer is an excellent way to try out methods in the Monitoring API without having to write any code. The widget presents a form showing the parameters for each method. Fill in the form, click the Execute button, and see the results.

You can also hide the widget by clicking the close button at the top of the panel, or expand it to full screen by clicking the fullscreen button.

Try It! buttons

Through the documentation, you will see Try It! buttons like the following accompanying some examples:

Try It!

Clicking the button brings up the API Explorer on the proper reference page and populates the fields as appropriate to the example. You will have to edit some of the fields to match your own project, such as the value for [PROJECT_ID].

See Tips for additional information about avoiding and fixing errors.

Accessing the API Explorer

The API Explorer is attached to the reference page for each REST API method. To find the widget, go to the reference page for a method, for example, the reference page for monitoring.projects.metricDescriptors.list.

Executing a minimal request

Most methods have some required parameters and some optional ones. The required ones are marked with a red bar until they are filled. You can execute a minimal request by supplying only the required arguments.

The metricDescriptors.list method returns descriptors for all of the available metric types in a project. The only required field is the name field. To retrieve this list for your project, supply the name of your project for name, using the form projects/[PROJECT_ID].

Click the button below to try it out, but before you click Execute button on the form, you need to change [PROJECT_ID] to the identfier for your project:

Try It!

The results of the method invocation appear in a box under the Execute button. Typically, the box will have a green header with the HTTP status code 200 in it, indicating the request succeeded. The results of the invocation are in the box:

The result of a successful method invocation

If the header is red and contains an HTTP failure code, the box contains the error message. See Tips for some pointers on resolving errors.

Supplying additional parameters

The list of parameters you see depends on the method to which the API Explorer widget is attached. The metricDescriptors.list method has more than just the name parameter, but name is the only required parameter.

When you provide only the project name, you get all the metric descriptors available in your project, and there are a lot of them. You can use the optional filter parameter to restrict the retrieval to a smaller set.

For example, fill in the following fields on the metricsDescriptor.list page. Substitute your project ID for [PROJECT_ID], but supply the other value as shown:

  • name: projects/[PROJECT_ID]
  • filter: metric.type=ends_with("utilization")

Executing this request returns only the descriptors for metric types whose names end with utilization.

Try It!

Using fields to limit output further

By default, the set of parameters that API Explorer shows corresponds to the parameters of the associated method. However, the API Explorer widget also has a set of extra fields that are not available via the method itself.

These parameters are hidden under the toggle Show standard parameters, which appears above the Authentication section:

"Show standard parameters" toggle

Click this toggle to expose the extra widget parameters. Click Hide standard parameters to hide them from view.

The most useful of these standard parameters is the fields parameter, which lets you select the fields in the returned output that you want to see. This is very useful in the API Explorer panel, where the output is displayed in a box. There is often a lot of output to scroll through.

For example, listing the descriptors for metrics ending with utilization still returns a lot of information. If all you are interested in is the name of the metric type and its description, you can use the fields field to specify those fields only.

To see the difference, fill in the following fields on the metricsDescriptor.list page. Substitute your project ID for [PROJECT_ID], but supply the other values as shown:

  • name, as before: projects/[PROJECT_ID]
  • filter, as before: metric.type=ends_with("utilization")
  • fields: metricDescriptors.type,metricDescriptors.description

Executing this request returns only the type (short name) of each metric and its description. The following is part of the output:

Try It!

Tips

Remember to change [PROJECT_ID]

Do not forget to replace [PROJECT_ID] with your project's ID. If you forget, you get the following result:

Forgot to change PROJECT_ID

Problems with the values

Here are some issues to watch for when using the API Explorer forms. These mistakes might cause errors or might be accepted but be treated like spelling errors in the API method:

  • Do not use quotation marks around field values of any type.
  • Be sure to quote strings appearing inside filters. Use double quotation marks (") and not apostrophes ('). See Supplying additional parameters for an example.
  • Do not use backslashes or URL-encoding in form fields. If needed, URL-encoding is performed on the field values when you execute the method.
  • Look at the value in the result box after executing the call. You might notice the problem there.
  • You might want to supply a value for the pageSize field, such as 2. This limits the amount of data that is returned as you debug your API call.

Bookmark URLs for debugging

After you get the output you want, bookmark the API Explorer URL. When you want to run the method again, paste the URL into your browser. You see the form already populated with your values. Make any necessary changes to the parameters, and click Execute to run the method again.

Authentication

There is an Authentication section on the API Explorer page, above the Execute button. You typically do not need to change anything here.

The default authentication mechanism is Google OAuth 2.0.

There is also a Show scopes toggle in the Authentication section. This shows you which Compute Engine scopes you have available. By default, all available scopes are enabled.

See Access Control for more information on these concepts.

Troubleshooting

If you still have trouble, see Troubleshooting the Monitoring API.

Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Monitoring