Trying out the API

In addition to viewing the SmartDocs API reference documentation, developers can use the Try this API panel to interact with your API without leaving the API documentation. In your portal, developers can send requests to your API and see the responses. Trying out your API in your portal helps your users understand what they need to do to get their own code working with your API.

If your API requires an API key or authentication, you must configure your portal so that your users can interact with your API. This page describes the requirements and configuration that you need to do so that developers can use Try this API. For each task, the minimum required Identity and Access Management role (or roles) required to complete the task is provided. For more information about IAM permissions, see the following:

Prerequisites

  • You must have already deployed your API to the App Engine standard environment. The gcloud app deploy command automatically creates a DNS entry on the appspot.com domain for your API so that it is reachable by the Endpoints Portal.
  • If your API requires an API key:

  • If your API requires authentication:

Configuring API Explorer settings

If your API requires an API key and/or Firebase or Auth0 authentication, you need to configure these settings before your users can try out your API. This section describes how to configure an API key and authentication settings.

Configuring an API key

To configure an API key in your portal:

  1. In the Google Cloud console, go to APIs & Services > Credentials.

    Go to the Credentials page

  2. In the Project drop-down list at the top Google Cloud console window, select the Google Cloud project that you created the API in.

    • If you have an existing API key that you want to use:

      1. Click Edit API key next to the API key you want to use.
      2. To the right of the API key, click Copy to copy the API key to the clipboard.
      3. Click Cancel.
    • If you need to create an API key:

      1. Click Create credentials, and then select API key.
      2. Copy the key to the clipboard.
      3. Click Close.
  3. Go back to your portal.

  4. Click Settings .

  5. Click the APIs tab and select your API from the drop-down list.

  6. In the APIs Explorer Settings section, paste the API key into the Google API key field.

  7. Click Save.

Configuring Firebase

To configure Firebase:

  1. Open the Firebase Console .

    • If you don't have an existing Firebase project:

      1. Click Add project and select the Google Cloud project name that your API is in.
      2. On the Authentication card, click Get Started.
      3. Click the Sign-In Method tab.
      4. In the Sign-in providers section, enable the providers that you want to use.
      5. In the Authorized domains section, click Add Domain and add your portal domain name (for example, endpointsportal.example-api.example.com).
      6. Click Web Setup. The customized code snippet is displayed. Leave the Firebase Console open because you need information from the code snippet in the following steps.
    • If you have an existing Firebase project:

      1. Go to Develop > Authentication.
      2. Click the Sign-In Method tab.
      3. In the Authorized domains section, click Add Domain and add your portal domain name (for example, endpointsportal.example-api.example.com).
      4. Click Web Setup. The customized code snippet is displayed. Leave the Firebase Console open because you need information from the code snippet in the following steps.
  2. Open another tab in your browser and go to your portal.

  3. Click Settings .

  4. On the Settings page, click the APIs tab and select your API from the drop-down list.

  5. In the APIs Explorer Settings section:

    1. Copy the value of the apiKey field from the Firebase code snippet and paste it into the Google API key field.
    2. Copy the value of the authDomain field from the Firebase code snippet and paste it into the Firebase auth domain field.
  6. Click Save.

See the Firebase documentation for more information.

Configuring Auth0

Use the following high-level task list to configure Auth0 and your portal:

Task 1. Make sure there is an Auth0 API for the Cloud Endpoints service.

Task 2. Configure Auth0 Application settings.

Task 3. Configure the Auth0 settings in your portal.

Task 1: Make sure there is an Auth0 API for the Endpoints service

  1. Log in to the Auth0 Dashboard.
  2. In the left navigation bar, click APIs. If there is an API Audience in the form of https://SERVICE_NAME, where SERVICE_NAME is the name of your Endpoints service, then you have already created an API. Continue with the next task to configure the Auth0 Application settings.

    Otherwise, create an API:

    1. Click + Create API.
    2. Enter a name.
    3. In the Identifier field, enter a URL in the format: https://SERVICE_NAME

      Replace SERVICE_NAME with the name of your Endpoints service. If you are unsure of the service name, see Getting the Service Name and Configuration ID for details on finding the name of your Endpoints service.

    4. Click Create.

Task 2: Configure Auth0 Application settings

  1. In the Auth0 Dashboard, click Applications in the left navigation bar.
  2. Select your Auth0 application or click + Create Application to create a new one.
  3. On the Settings tab of your application, scroll down and add your Portal's OAuth Redirect URL to the Allowed Callback URLs field. Your portal's OAuth redirect URL is your portal's URL plus /oauth/redirect (for example, https://endpointsportal.example-api.example.com/oauth/redirect).

    The Allowed Callback URLs field accepts multiple URLs separated by a comma. Be sure that the URL that you enter doesn't include a trailing / character.

  4. Click Save Changes.

    Leave your Auth0 Settings browser tab open because you need information from there in the following steps.

Task 3: Configure Auth0 settings in your portal

  1. Open another tab in your browser and go to your portal.
  2. Click Settings .
  3. On the Settings page, click the APIs tab and select your API from the drop-down list.
  4. In the APIs Explorer Settings section:

    1. Copy the value of the Client ID field in the Auth0 Dashboard and paste it into the Auth0 client ID field.
    2. Copy the value of the Domain field in the Auth0 Dashboard and paste it into the Auth0 domain field.
  5. Click Save.

For more information on configuring Auth0, see the Auth0 Dashboard overview in the Auth0 documentation.