Was this helpful?

Use Drupal's "Basic Page" content type to add documentation about your API, such as how-to guides and API reference documents, to your Developer Services portal, and include content such as videos, screencasts, or code downloads. 

Note: Developers will use apps to access resources in your API products. In general, developers will use your developer portal to add those apps. Ensure that your documentation includes instructions for adding apps though your developer portal. You can use Instructions for adding apps as a starting point. Those instructions cover how to add apps through the default developer portal.

The Documentation page is set up with some initial entries organized in various categories such as "Getting Started" and "Tutorials". The page is a starting point for you to edit. In this way you can add you own content entries and organize those entries in the way you want.

Adding the Documentation home page

By default, the Documentation home page is at <siteURL>/documentation on your developer portal. The default Home page of the developer portal contains a link to this page in the box at the top of the Home page:

You can also add a Documentation link to this page in the main menu of the developer portal menu.

However, the Documentation home page does not exist by default, so you must create a new page on the developer portal at the correct URL.

To add the Documentation home page to your developer portal:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > Add content > Basic page in the Drupal administration menu.
  3. Enter the title of the document, such as Documentation Home, and the content of the first page.
  4. Click Edit summary to add a Summary.
  5. Click the Menu settings item below the Body section.
  6. Select Provide a menu link, add the link title, and select <Main menu> in the Parent Item.
    This adds a link to the main menu for your Documentation Home page.
  7. Click the URL path settings item below the Body section.
  8. Deselect Generate automatic URL alias, and set the URL alias to documentation.
    By default, the URL of a page is <siteURL>/content/pageName. By setting the URL alias, you set set an explicit URL of the page, in this case to <siteURL>/documentation.
  9. Save the page.
    You should now see a link to the page in the menu bar, and the link in the in the box on the home page should now work.
    As an administrator, you'll also see content administration buttons such as View and Edit. Non-administrators won't see those.

Adding a child page to your documentation

As you add child pages to your documentation:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > Add content > Basic page in the Drupal administration menu.
  3. Enter the page title and the content.
  4. Click Edit summary to add a Summary.
  5. Click the Menu settings item below the Body section.
  6. Select Provide a menu link, add select the documentation home page menu item.



    This adds a current page as a child of the main menu for your Documentation Home page.
  7. You should now see a link to the page on the Documentation Home page menu.

Editing a documentation page

To edit a page:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Navigate to the page in the developer portal.
    You can also click Content in the Drupal administration menu to list all your pages and select one.
  3. Select the Edit tab on the page.


     
  4. Open a visual editor by selecting Full HTML or Filtered HTML in the Text Format drop-down menu below the Body section.
    You should see the content of the page displayed in the editor.
  5. Edit the page as necessary.

  6. Click Save.

Displaying any documentation page

To display the content of a document:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content in the Drupal administration menu.
  3. Select the document you want to view.

 

Rearranging the order of pages

You can change the sequence and nesting level of pages in the Documentation Home menu.

To rearrange pages in the Documentation Home menu:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. In the Drupal administration menu, select Structure > Menus > Main menu.
  3. Each item in the menu has an icon next to it. To move an item, click and drag the icon to move it to a new location.
    Dragging an item with child items also moves the children.


     
  4. Click Save Configuration.

Editing footer pages

The footer for the portal contains three social icons for Twitter, Facebook, and LinkedIn and links with the following URLs:

  • Privacy Policy to the URL <siteURL>/privacy-policy
  • Terms & Use to the URL <siteURL>/terms-use
  • Contact pages to the URL <siteURL>/contact-us

Edit these pages to add your own content.

If these pages do not exist, create them:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > Add content > Basic page in the Drupal administration menu.
  3. Enter the title of the document, such as Privacy Policy, and the content of the page.
  4. Click Edit summary to add a Summary.
  5. Click the URL path settings item below the Body section.
  6. Select Generate automatic URL alias, and set the URL alias to privacy-policy.
    By default, the URL of a page is <siteURL>/content/pageName. By setting the URL alias, you set set an explicit URL of the page, in this case to <siteURL>/privacy-policy.
  7. Save the page.
  8. Repeat this process for the Terms & Use and Contact pages. 

To edit the content of a footer page, such as the Privacy Policy, Terms of Use, or Contact Us page, in your developer portal:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Navigate to the page by clicking its link in the footer. For example, click the Privacy Policy link.
  3. Click the Edit tab in the page to open the editor.
  4. Change the contents of the Privacy Policy page as appropriate.
  5. Click Save.
  6. Repeat this process for the Terms & Use and Contact pages.

To edit the social icons, such as the Twitter, Facebook, and LinkedIn icons, in your developer portal:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Structure > Blocks in the Drupal administration menu.
  3. Scroll down the Blocks page until you see the Site-wide Default Footer block.
  4. Select the configure link corresponding to the Site-wide Default Footer block.
  5. In the Custom Content area, right-click on a social icon and select Edit Link from the pop-up menu. Or, delete the icon from the Custom Content area to remove it.
  6. Select Save block to save your changes.

Adding JavaScript to a portal page

You can add JavaScript to any portal page. The easiest way to add JavaScript is to edit the page, and then:

  1. Select Full HTML as the Text Format.
  2. Select the Source button to edit the HTML source code for the page.
  3. Add your JavaScript to the page. For example, to pop up an alert box when the page loads, add the following code:

    <script language="JavaScript">
        alert('Welcome to my page!');
    </script>

The Full HTML text format can be configured to limit the HTML tags allowed on the page. For example, it can be configured to prohibit the use of the <script> tag. To determine the settings of the Full HTML text format, select Configuration > Content authoring > Text formats > Full HTML in the Drupal administration menu. If the Limit allowed HTML tags checkbox is selected, then check the allowed HTML tags in the Filter processing order area of the page.

Some considerations on using JavaScript:

  • If you are going to reference a JavaScript file, don't do it in the source code of a node because that creates a static link. Instead use PHP code so you can create a dynamic link. In that way, if the location of the JavaScript file changes, you do not have to update all of the portal pages that reference it.
  • If you want to include a JavaScript file, add it to the portal theme. Or, if it is part of a Drupal module, add it to the module.
  • You can also use the Drupal drupal_add_js function to add JavaScript in Drupal. For more information, see https://api.drupal.org/api/drupal/includes!common.inc/function/drupal_add_js/7.

Checking for broken links

It's good practice to check your content for broken links. By default, the developer portal is set up to check various types of pages for broken links. For example, links are checked in basic pages, articles, blog entries, and forum topics.

To add to or remove page types from the link check:

  1. In the Drupal administration menu select Configuration > Link checker.
  2. Select the checkboxes for the page types in which you want links checked. Uncheck the checkboxes for the page types in which you don't want links checked.

Configuring search

The developer portal provides a built-in search engine implemented by Apache Solr, which uses the Apache Lucene search library. This is the search engine for the site itself, which the user accesses through the search box in the upper-right corner of all portal pages.

External search engines, such as Google, can also index your portal. The developer portal lets you control whether or not external search engines can index your portal.

Configuring Apache Solr

You can configure Apache Solr to control the content types to index, to force an index, and to perform additional configuration tasks.

To configure Apache Solr:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. In the Drupal administration menu select Configuration > Search and metadata > Apache Solr search.
  3. Use this page to configure Apache Solr.

Disabling Google indexing

It's also good practice to index your content, and make it available to search engines. By default, your content is indexed by the Google indexer. However, you have the option of disabling Google indexing. You might want to do this if your developer portal is not ready for public use and so you don't want your content to be publicly searchable.

To disable Google indexing:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Modules in the Drupal administration menu.
  3. Select the Meta tags section to expand the section.
  4. Uncheck the Meta tags checkbox.
  5. Click Save configuration.
  6. In the Drupal administration menu select Configuration > Search and metadata > Metatag.
  7. Select Override operation for the Global type.
  8. Click the Advanced section to open it.

  9. Check the checkbox for Prevent search engines from indexing this page.
  10. Click Save.

Notice that there are other search-engine related options in the Advanced section of the Global page. For example, you can check a checkbox to prevent search engines from following links on a page. Check one or more of these checkboxes as appropriate.

Instructions for registering apps

As mentioned earlier, it's important that your documentation include instructions on how developers can register their apps though your developer portal. You can use the following instructions as a starting point — these instructions cover how to register apps through the default developer portal.

To register an app through the default developer portal:

  1. Select  My apps below your username in the login menu. This displays the My apps page.
  2. Click the Add  (+)  new app  icon. This displays the Add app page.

    Add app icon

  3. Enter appropriate values in the Add app page:
    App name Provide a unique App Name for your app.
    Callback URL

    Provide the callback URL to which the OAuth call should return. By default, this value is required even if your APIs do not use OAuth. If your APIs do not use OAuth, enter a dummy value such as my.site.com.

    Alternatively, you can select Configure > Dev Portal Settings in the Drupal administration menu to configure the portal to not require the Callback URL. On the Dev Portal Settings page, scroll down to the Callback URL Handling section to make your selection. However, this setting applies to all apps so you should only do this if none of your API products use OAuth.

    Product Select the API product from the drop-down list to gain access to that product.
  4. Click Create App. This will register the app and generate the API key for the app.

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?)