Developer portals with social publishing features are increasingly being used for communication with the developer community. This includes communicating static content, such as API documentation and terms-of-use, as well as dynamic community-contributed content such as blogs and forums.

As an API provider, you need a way to expose your APIs, educate developers about your APIs, sign up developers, and let developers register apps. Exposing your APIs to developers is only part of creating a truly dynamic community. You also need a way for your developer community to provide feedback, make support and feature requests, and submit their own content that can be accessed by other developers.

Apigee Edge provides you with a Developer Services portal that you can use to build and launch your own customized website to provide all of these services to your development community. Every Edge customer can create their own developer portal, either in the cloud or on-prem. The following figure shows the home page of the default developer portal:

The developer portal is essentially a content management system (CMS) based on the open source Drupal (http://www.drupal.org) project. Drupal provides a core set of features in the form of modules that make it easy for you to build the content for, as well as manage, websites.

Out of the box, the developer portal lets you create API documentation, supports blogging, and provides threaded forums. You can also customize the developer portal to meet your specific requirements. Customization lets you modify the portal appearance and also the way that developers interact with the portal.

You use the Drupal menu to perform most customization. If you log in to the portal as a user with admin privileges, the Drupal menu appears at the top of every portal page:

Administration controls the process where developers request access to the portal, how developers register the apps that access your APIs, how you assign developers specific roles and permissions related to your APIs, and when to revoke developer access to APIs.

You also use the developer portal to configure and control monetization. Monetization gives developers self-service access to Billing & Reports, Catalog & Plans, and monetization-specific settings through the developer portal.

Types of portal users

The following image shows two types of portal users:

  • Developers make up the community of users that build apps by using your APIs. App developers use the portal to learn about your APIs through an API console or SmartDocs, to register an account on the portal, to register apps that use your APIs, to interact with the developer community, and to view statistical information about their app usage on a dashboard.
  • API team is the API provider that creates portal content, makes their APIs available to app developers, provides API documentation, and provides a mechanism for developers to register apps and obtain API keys. The API team performs basic configuration of the developer portal to:
    • Configure automatic or manual requests for API keys
    • Maintain API documentation, forums, and blogs and optionally revision all changes
    • Add API call tracing in real time from within the portal using Apigee’s Console To-Go
    • Handle user comments and forum moderation
    • Enforce Role Based Access Control (RBAC) to control access to features on the portal. For example, an administrator can enable controls to allow a registered user to create forum posts or use test consoles
    • Customize email notifications to both administrators and developers for user creation and approvals
    • Customize web forms such as "contact us" pages

Not shown in this figure is a third type of portal user - the API product manager. The API product manager is responsible for defining how the API team builds the portal, including:

  • Defining how APIs are packaged into products
  • Defining the rules for app approval
  • If Monetization is enabled on the portal, defining the pricing and billing plans for API products. For more on Monetization, see The basics of monetization.

Customizing the developer portal

As an API provider, consider how to customize the developer portal to best fit your APIs and to provide the necessary information for your developer community to use your APIs. Some considerations for your custom portal include:

  • Easy access to your APIs
  • Documentation, such as how-to guides and reference documents
  • Community-contributed content such as blogs and discussion forums
  • Sample code
  • An easy sign-up process where new developers, apps, and APIs can be approved quickly
  • Managed rights and credentials
  • Tiered access control
  • A look and feel that matches your organization

The portal comes predefined with a basic configuration. For example, out of the box the portal is configured to allow anyone to register as a developer, but an administrator must approve each registration before the developer can log in to the portal. After registration approval, the developer can then register an app to request an API key and use the portal to access API resources.

The steps in the default registration process are:

  1. The developer registers through the developer portal. In response, the portal sends an email to administrators to approve the account.
  2. An administrator approves the account, and an email is sent to the developer letting them know that they can now log in.
  3. The developer registers an app and selects the API products used by the app. In response, the portal assigns a unique API key to the app.
  4. The developer passes the API key when making requests to your API.

This out of the box experience is highly customizable. For example, you can override the default registration and authorization scheme so that a new developer is automatically approved and logged in after registration. Or, you can require the developer to accept a set of terms and conditions before they can log in for the first time.

You also have complete control over the content available on the developer portal. Out of the box, the developer portal presents sample content such as API documentation, blog posts, and forum discussions. You can provide your own content, and customize the appearance of each content type.

For more information, see Customize the appearance.

Administering the developer portal

Developers use your developer portal to access and use your API. Administrators perform account management tasks, such as:

  • Customizing the developer registration process, including registration fields, built in Captcha, and automatic or manual approval
  • Adding or approving developers. By default, any developer can register through the developer portal but needs to be approved by an administrator through the Dev Portal user interface.  Administrators can also create developers directly on the portal. The portal then automatically emails the developer that an account has been created for them.
  • Modifying a developer's account. For example, administrators can change the user's account status from active to blocked or change the developer’s profile information such as the company’s name.
  • Removing a developer. Administrators can disable or delete a developer's account.
  • Assigning roles and permissions: Administrators can assign a specific role to a developer account. A role is associated with various permissions, such as permission to create books or other content. You can also change the permissions associated with a role or make new roles.

For more information, see Add and manage user accounts.

Adding an API Console To-Go

Many portals incorporate an API Console To-Go, which is a GUI provided by Apigee that developers use to explore and test your API without having to write any code. The console presents a point-and-click interface that makes it easy for developers to submit requests to your API, and to view the request and response objects. It also displays documentation to make it easy for developers to learn how to use your APIs.

The following image shows the API Console To-Go:

Create and configure the Console To-Go separately from your developer portal. Once created, you can integrate the Console To-Go with your portal, or make it available as a standalone utility.

For more information, see What's an API Console?.

Summary of developer portal features

The following table contains a summary of the developer portal features:

Feature Details
Browser support

See Supported software.

User registration

  • Manual or automatic approval of new developer accounts
  • OpenID integration
  • Single Signon (SSO) support with Twitter, Google, and GitHub
  • CAPTCHA
  • Custom fields

User management

  • Create and edit users
  • Assign roles

Portal appearance

  • Customize by CSS, images, and Drupal modules

Content and community management

  • Open source (Drupal) based
  • Template-based content creation
  • Content types available out-of-the-box for API documentation, blogs, forum, FAQ
  • Automated links for Del.icio.us, Digg, Twitter
  • Revision control for content
  • Tags, keywords, and archive for blogs
  • Integration with Google analytics
  • Customizable popularity criteria for content
  • Admin moderated forum posts and comments
  • Different access based on custom roles, signed-in, and anonymous user

Permissions

  • Role based access rules

API key management

  • Built-in app registration
  • Support for automatic or manual API key approval
  • Administrators can revoke keys

Email

  • Specify your SMTP server
  • Configure when the portal send email to developers
  • Control the content and format of email generated by portal

Blogs

  • Create, edit, and publicize blog posts
  • Role-based permissions to restrict blog creation to specific user types

Forums

  • Create threaded developer forums
  • Create additional forum categories as necessary
  • Role-based moderation

Documentation

  • Document your APIs
  • FAQs
  • Examples
  • Tutorials

Menus

  • Control menu appearance and content

Search

  • Built-in Apache Solr search
  • Search specific content. For example Forums or Blogs
  • Control Google indexing

Link Checker

  • Check pages for broken links.
  • Control the link check list

 

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)