Configuring app registration

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Developers use the My Apps page on the Developer Services portal to register apps. Developers access the My Apps page from the main menu of the portal:

To register a new app, the developer selects the Add a new app button on the My Apps page.

The portal then displays the default app registration form:

By default, the developer only has to specify the app name, callback URL, and the list of API products to add to the app.

As an API provider, you have a complete control over the app registration process. For example, you can configure:

  • The list of API products available on the portal
  • Whether there is a default API product
  • Whether the callback URL is required
  • Whether the API key is manually or automatically approved for an API product
  • Whether any other information is required on the Add App page to register the app

This topic describes how to configure the app registration process for your portal. However, this topic does not describe how to create API products. For more, see:

You can configure the portal to prohibit developers from being able to create, delete, or edit apps based on the role assigned to the developer. For example, you might configure the portal to create a single, default app for all developers when the developer registers. Then, you only allow some developers to add new apps, possibly based on a fee structure or other characteristics of the developer. Use roles and permissions to control which developers can create, delete, and edit apps. See Add and manage user accounts for more.

Specifying the API products available on the portal

There are two ways in which you can specify the API products that are available when a developer accesses the portal:

Specifying the access level when creating an API product

When you create an API product, you specify the access level option of the product, as shown below:

For more information about how the access level impacts the availability of the API product in the Drupal 7 developer portal, see Access level.

Restricting access to an API product based on roles

By enabling the API Product Role Access Drupal module, you can specify the roles that can access each API product.

To restrict access to an API product based on the developer roles:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Review the dev portal roles and user assignments:
    • Select People > Permissions > Roles in the Drupal administration menu and add or edit the developer roles and permissions, as required.
    • Select People in the Drupal administration menu and edit user and role assignments, as required.
  3. Select Configuration > Dev Portal > API Product Role Access in the Drupal administration menu.
  4. Select the roles that you want to be able to access each API product.
  5. Click Save configuration.

Configuring how a developer associates API products with an app

To register a new app, a developer selects the Add a new app button on the My Apps page to open the Add App form:

Based on how you configure the portal, the developer can select one or more API products to associate with the app at the time of app registration. Or, you can specify a default product that is assigned to all apps.

The following configuration options are available on the portal to control API product selection when registering an app:

  • Do not associate apps with any API Product.
  • Associate all apps with one or more Default API Products (configured below). Developers cannot add any other API products to the app.
  • Allow selection of a single API product, but do not require it.
  • Require selection of a single API product.
  • Allow selection of multiple API Products, but do not require any.
  • Allow selection of multiple API Products, and require at least one.

You can also control the HTML element that appear on the form that the developer uses to select the API product. Options include:

  • Dropdown lists.
  • Checkboxes or radio buttons. Checkboxes appear when the developer can select multiple API products and radio buttons appear when the developer can select only a single API product.

To set the option for API product selection:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > Dev Portal Settings > Application Settings in the Drupal administration menu.
  3. On the Application Settings page, expand the API Product settings area.
  4. Under API Product Handling, select the option that controls API product selection.
  5. If you specify the option "Associate all apps with one or more Default API Products (configured below)", set a default product under Default API Product.
  6. Under API Product Widget, select the HTML element used by developers to select the API products.
  7. Save the configuration.

Configuring callback URL handling

If an API proxy in your API product uses "three-legged OAuth" (authorization code grant type), developers need to specify a callback URL when they register their apps. The callback URL typically specifies the URL of an app that is designated to receive an authorization code on behalf of the client app. In addition, this URL string is used for validation. The client is required to send this URL to Apigee Edge when requesting authorization codes and access tokens, and the redirect_uri parameter must match the one that is registered. For more information, see Implementing the authorization code grant type.

To control the callback URL for API product selection:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > Dev Portal Settings > Application Attributes in the Drupal administration menu.
  3. On the Application Settings page, expand the Callback URL settings area.
  4. Under Callback URL Handling, select one of the following options.
    • Callback URL is required for all developer apps.
    • Callback URL is optional for all developer apps.
    • Callback URL is neither required nor displayed.
  5. Save the configuration.

Displaying analytics for app usage

The portal can display analytical information about app usage. If the display of analytics is enabled, app developers can see the analytics on the My Apps page for each app. For example, a developer can display the following analytics for an app:

  • Throughput
  • Max response time
  • Min response time
  • Message count
  • Error count

To enable analytics on the portal:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > Dev Portal > Application Settings in the Drupal administration menu.
  3. On the Application settings page, expand the App performance settings area.
  4. Select the Show Developer App analytics tab check box.
  5. Select either Test or Production for Environment to query for analytics data. For a publicly available portal, typically you will select Production.
  6. Save the configuration.

To display analytics on the portal for an app:

  1. Select the app name on the My Apps page.
  2. Select the Analytics link for the app.
  3. Select the type of analytics to display and the date range:
  4. The selected information appears:

Manually approving or revoking an API key for an API product

When a developer adds an API product to an app and then registers the app, the portal returns back to the developer the API key for that app. The developer then uses that API key to access the API proxies bundled by the API product associated with the app.

You control the key approval process for each API product when you create the API product:

The approval process can be:

  • Automatic - An approved API key is returned by the portal for the API product when the developer registers the app. You can later revoke an automatically approved key.
  • Manual - An API key is returned by the portal when the developer registers the app, but the key is not activated for any API products that use Manual key approval. An administrator has to manually approve the API key, either in the Edge management UI or API, before it can be used by the developer to access the API product. You can later revoke a manually approved key.

See Create API products for more information.

If your portal lets a developer add multiple API products to an app, the developer might add some products with Automatic key approval and some with Manual. The developer can use the returned API key for all automatically approved API products immediately while waiting for final approval for those products that require Manual approval.

To see the list of API products for an app, and the status of the key approval for the API product, a developer selects the name of the app on the My Apps page and then selects the Products link:

In this example, the Premium Weather API product uses Manual approval, and is waiting for an administrator to approve the key. The Free API Product uses Automatic approval and the use of the key to access it has been approved.

To manually approve or revoke a key:

  1. Log in to the Edge management UI as a user with administration privileges for your organization.
  2. Select API Platform in the dropdown box in the upper-right corner.
  3. Select Publish > Developer apps to open the list of developer apps.
  4. Select the Pending button to see the list of apps with pending key requests:

  5. Select the app name that you want to approve.
  6. On the app details page, select the Edit button in the upper-right corner.
  7. In the list of API products for the app, under Actions:
    • To approve the key, select the Approve button for each API product that requires manual approval.

    • To revoke an approved the key, select the Revoke button under Actions for an API product to revoke access.

  8. Save the app. The API key is now approved.

Controlling API product and app caching

Information about API products and developer apps is stored remotely from the portal on Apigee Edge. That means changes to API products and apps can be performed from the Edge UI or API, without going through the portal. For example, when a backend administrator adds a new API product, the portal is not immediately updated with that information.

To make sure that the portal stays in synch with the Edge backend, you can manually trigger an update of the portal cache, update the caches automatically when the portal's cron job runs, or both. For example, if you configure the cron job to run frequently, such as every 5 or 10 minutes, you might not want the overhead of updating the API products and developer app caches that frequently. In this situation, you can then trigger the cache update manually. But, if the cron job runs every hour or two hours, the time required to update the caches might not have much of an impact.

By default, the portal is configured to rebuild the API product and developer app caches every time cron runs.

To specify whether or not to rebuild the API product and developer app caches every time cron runs:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. From the Drupal menu, select Configuration > Dev Portal Settings > Application Settings.
  3. Check or uncheck Rebuild API Product and Developer App caches every time cron runs.
  4. Save your settings.

To update the caches manually:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. From the Drupal menu, select the Home icon > Flush all caches.

Customizing the form fields used to register an app

When the developer registers an app, the portal display the default form:

As an API provider, you might want to modify this form to prompt the developer to provide additional information such as a customer ID, the target platform of the app, or other information. The portal provides you with a the ability to add new fields to this form. These fields can be:

  • Required or optional
  • Displayed by different HTML elements, such as text boxes, radio buttons, check boxes, and more
  • Can be set to appear anywhere on the form between the Callback URL field and the Product field

To learn how to customize the app registration form that is available from the developer portal, watch this video.

For example, the following form shows a required field for Customer ID and an optional field for target platform:

When you add new fields to the form, the field values are automatically uploaded to Edge, along with all the other fields, when the developer submits the form. That means you can view or modify those fields on Edge, or use the Edge management API to access those fields from a script.

For example, view the new form fields In the Edge management UI by going to Publish > Developer Apps, and then selecting the app name. The new field values appear under the Custom Attributes area of the page with a name that corresponds to the field's internal name:

The field values are also displayed in the Details area of the app on the developer's My Apps page:

The developer can also edit the values by selecting the Edit link for the app on the My Apps page.

The procedures below describe how to configure the app creation forms by using the administrator interface. A Drupal developer can perform additional customizations, including modifying the 'My Apps' page, by using custom hooks. To learn more on how change behaviors through code, see the app API examples in the file: /profiles/apigee/modules/custom/devconnect/devconnect_developer_apps/devconnect_developer_apps.api.php.

To add a field to the app registration form:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Ensure that the DevConnect App Attribute Management module is enabled.
  3. Select Configuration > Dev Portal Settings > Dev Portal App Attributes in the Drupal administration menu.
  4. Select the Add Dev Portal App Attribute button at the top of the page.
  5. Configure the field. For example, for the Customer ID field shown above, use the following settings:
    • Internal Name = cust_id. This is the name of the variable used to store the field value.
    • Public Name = Customer ID
    • Description = Enter your customer ID.
    • Select the check box for Require this attribute
    • Select the check box for Display this attribute.
    • Widget = Text Box
    • Select Save to return to the Dev Portal App Attributes page.
  6. Select Save Changes.
  7. Select the Home icon > Flush all caches from the Drupal menu.
    You might have to clear your browser cache before the new field appears on the form.

To add an optional field for the developer to specify the platform for the app, set the field attributes as:

  • Internal Name = intended_platforms
  • Public Name = Platforms
  • Description = Specify one or more platforms for your app.
  • Clear the check boxes for Require this attribute
  • Select the checkbox for Display this attribute.
  • Widget = List of Checkboxes
  • Select Save to return to the Dev Portal App Attributes page.

To reorder the attributes on the form:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > Dev Portal Settings > Dev Portal App Attributes in the Drupal administration menu.
  3. Select the plus, +, symbol under the Name column and drag the property to the location where you want to display it in the form.
  4. Save your changes.