You're viewing Apigee Edge documentation.
Go to the
Apigee X documentation. info
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 video introduces the Apigee Developer Services portal.
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 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
- 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 Monetization overview.
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:
- The developer registers through the developer portal. In response, the portal sends an email to administrators to approve the account.
- An administrator approves the account, and an email is sent to the developer letting them know that they can now log in.
- 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.
- 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.
Summary of developer portal features
The following table contains a summary of the developer portal features:
| Feature | Details |
|---|---|
| Browser support | |
|
User registration |
|
|
User management |
|
|
Portal appearance |
|
|
Content and community management |
|
|
Permissions |
|
|
API key management |
|
|
|
|
|
Blogs |
|
|
Forums |
|
|
Documentation |
|
|
Menus |
|
|
Search |
|
|
Link Checker |
|