Create your own API 7.x-1.x Site in Drupal 7

Last updated on
17 December 2018

Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites

This documentation is deprecated.

Note: This branch of the API module is no longer supported. Please use the 7.x-2.x branch instead, which has a stable release.

Introduction

These instructions are for installing the API Module, using version 7.x-1.x, in a Drupal 7 environment, to build a site similar to http://api.drupal.org. If you're upgrading from a Drupal 6 API site, see the bottom of this page for notes. Also note that these instructions are only for versions in the 7.x-1.x of the API module -- the 7.x-2.x branch has a different setup. Note that there is also a DrupalAPI distribution that will setup an API site for you.

Note that the API module can parse any documented Drupal code, including contributed modules, independent of Drupal core version. This means the Drupal code you use to run your site need not necessarily be the same as the code you are parsing and displaying. In fact, it is a good idea to keep the code you are parsing and displaying outside of the site running the API module. These instructions are made with that assumption. It also means that although the API module runs with Drupal 7, you can use it to build a site that displays code from Drupal 7, 8, 5, 4.7, etc.

Useful terminology

The following is a list of terms used on this page and within the API module:

project
A module, theme, Drupal Core, or other group of files that the API module is parsing.
branch
A particular version of a project's files (6.x-1.x, 7.x, etc.).
repository
A directory where you store files for a particular branch/project
Reference branch
An external web site that is used to make links to externally-defined functions (such as making links to php.net for the built-in PHP functions or to api.drupal.org for Drupal Core functions).
update (a branch or reference branch)
Scan the branch for updated files, or the PHP reference branch for updated function definitions. Files that have changed since the last time they are parsed will be added to the queue of files to reparse. Updates are normally done during cron runs.
parse or reparse (a file)
Read in a file and save its information in the API module database, for display on the API site (replacing any previously-stored information from a previous parse of the same file). Parsing is normally done during cron runs.

Step 1: Install Drupal and modules

This section assumes you want to have a new Drupal installation for your API site. If you want to use an existing Drupal 7 installation, skip the download/install Drupal steps.

Requirements note: Some features of the API module require PHP version 5.4 or higher, and the API module will not run without it.

  1. Download Drupal 7 at: http://drupal.org/project/drupal
  2. Install Drupal. See: http://drupal.org/getting-started/install.
  3. Download and install/enable the latest version of the Ctools module.
  4. Download and install/enable the latest version of the 7.x-2.x branch of the Libraries API module.
  5. Download the latest version of the 7.x-2.x branch -- at least version 7.x-2.2 of the Grammar Parser project (if it has been released; otherwise, the latest 7.x-2.x-dev download). Unpack it to your sites/all/libraries directory, rather than installing it in sites/all/modules as a module.
  6. Download and install/enable the latest version of the 7.x-2.x branch -- at least version 7.x-2.1 of the Grammar Parser Library module. Note that if you use Git to get the development version of this module (or download a development version zip), you will need to add a version string to the .info file. Hopefully if you are adventurous enough to use development versions, you know how to do this... Using a released version of this (fairly simple) module is recommended anyway, since it is stable.
  7. If you are using version 7.x-1.3 or later of the API module (or a development version from 10 January 2013 or later), you will also need to download and install/enable the Views module.
  8. Download and install/enable the latest stable version of the API module within the 7.x-1.x branch (these instructions do NOT work for the 7.x-2.x branch). The 7.x-1.x-dev development version is not necessarily stable, and may rely on patched versions of Grammar parser and other modules to function correctly, so unless you really want to be on the cutting edge and have an unstable site, use a stable release, and read the release notes before upgrading. If you choose to install the development version, be sure to read the release notes, and you'll also probably want to subscribe to the issues in the API module to follow development. Check the API module home page for notes that may affect you.
  9. Change permissions for the API module as needed at: admin/people/permissions

Step 2: Set-up code "repositories"

Once you have Drupal and the modules installed, you need to download some code to parse and display. There are many ways to do this; here we illustrate how to download the Drupal 7 Core code base using Git (with notes on how to download other code and using other methods).

Note: If you are setting up a site for a contrib project, you no longer need to get Drupal Core -- you can have your site link to api.drupal.org instead -- see the section on reference branches in the "optional" steps section below. But you'll still need to set up a repository for the contrib project you're trying to display API documentation for.

  1. Create a place for your code to go. It needs to be in a place that your web server can access (i.e., within your web document root). Command line for this:
    mkdir -p /path/to/your/code/repos/
    cd /path/to/your/code/repos/
  2. Create a subdirectory for the Drupal 7 Core code (or whatever other code you want to display). Command line for this:
    mkdir drupal-7; cd drupal-7
  3. Get the most recent version of the Drupal 7 code base (see Version control instructions for Drupal 7.x and the Git handbook for help). If you want to display code from some other project or branch, you can find the relevant git clone command by going to the project page and visiting the "Version control" tab).

    Here's the command to get the Drupal 7 code from Git:
    git clone --recursive --branch 7.x http://git.drupal.org/project/drupal.git

  4. As an alternative to the previous step, if you don't want to use Git to keep the code updated, you could also just download the Drupal 7 tar.gz or zip archive from http://drupal.org/project/drupal and unpack it into your repository area (or another project's code from its project page).
  5. Get the extra developer documentation using Git from the "Documentation" project (http://drupal.org/project/documentation), and put it in a separate directory. In Drupal 7, this includes the global variable documentation, the Form API reference, and the API documentation landing page. In Drupal 6, it also contains hook documentation. In Drupal 8, it's just the Form API reference. Here's an example command for Drupal 7:
    git clone --recursive --branch 7.x-1.x http://git.drupal.org/project/documentation.git

Repeat these steps to create repositories for Drupal 6, Drupal 8, other projects, etc. Put each branch of each project in its own directory.

Note: The API module will not index code in "hidden" directories (directories whose names start with "."). It also skips directories called "CVS", as it scans your directories and their subdirectories.

Step 3: Set-up API module to index code in repositories

The last required step is to tell the API module where your code repository is, by setting up a "project" and a "branch", and then indexing the code so it can be displayed. The API module has concepts of "projects" and "branches". Projects correspond to projects on Drupal.org, such as "Drupal Core", "Views", "Zen Theme", etc. Branches correspond to major versions within a Project, such as "7.x" or "7.x-2.x". In the API module, a code repository is designated as a "branch". Here's how to set that up:

  1. Go to the site you set up in Step 1, and add a new Project at: admin/config/development/api/projects/new (you can navigate to this page starting from the admin/config "Configuration" page in your Drupal site -- it's in the Development section under "API reference"). Fill in the form with the short name of the project (zen, views, drupal, etc.), and the human-readable name (Zen, Views, Drupal Core, etc.). For the Type field, enter module, theme, core, etc. Save the new project.
  2. Click on the Branches tab, and add a new branch (at admin/config/development/api/branches/new). Fill out the form with the following values:
    Project
    The short name of the project you created in the previous step.
    Core compatibility
    6.x, 7.x, etc.
    Preferred
    If you are going to include multiple branches within the same core compatibility (e.g., Views 6.x-2.x and 6.x-3.x), mark only one of them as "preferred".
    Branch Identifier
    This is an identifier for this branch within this project, and is used as a URL suffix and in other places. Use "7", "7.x", "7.x-2.x", etc.
    Branch title
    This should include the project name, since it has to stand alone in breadcrumbs and link titles. So it should be something like "Drupal 7", "Views 7.x-3.x", etc.
    Directories
    This is a list of absolute paths to the place(s) where your code is. This is where we put in the value from Step 2, such as /path/to/your/code/repos/drupal-7. You can also exclude specific subdirectories by filling out the Exclude Directories field, and exclude files and directories by regular expression by filling out the Regular Expressions field (version 7.x-1.2 and later only). If you are making a Drupal Core branch and you want to include the Documentation repository, put the location of your main Drupal repo on one line, and the Docs repo on another line, in the Directories box.
    Update frequency
    The API module, during cron runs, checks branches to see if any files have changed since the last time they were parsed. If you plan to have a lot of projects and branches on your site, you might want to set the update frequency to a longer time, so that not every branch is checked for updates during each cron run.

    Click Save Branch.

  3. On the Overview page, make sure that your default project and core compatibility are set correctly.
  4. Optionally (recommended!), edit the "PHP Reference" branch, and set its update time to a longer time (e.g., one week instead of one second). This will ensure that php.net is not checked for updated PHP functions every cron run (which is a waste of time).
  5. Process the queue to index the branch. You can do this in any of the following ways:
    • Install Queue UI, and use its UI to process the 'api_parse' queue.
    • Run cron (from admin/config/system/cron) until your new branch is indexed. You can monitor the parsing status of your site on the Overview tab. You can also see which parsing and branch update jobs have run in the Recent Log Entries report (assuming you have the Database Logging core module enabled).
    • If you use drush, you can use drush cron to run cron, and if you have a new-enough version of Drush, you can use drush queue-run api_parse to run the parsing jobs.
  6. If the queue counts displayed by the script or on the Overview page are not down to zero, run the script or cron again until all the parsing is finished.
  7. Go to your new api documentation at path: api. The content should resemble the content at http://api.drupal.org.

Optional steps

  • Enable the API navigation and search blocks at: admin/structure/block
  • If you are setting up an API reference site for a contrib project (module, theme, etc.), and you want to make Drupal Core functions turn into links, you have two choices: (a) you can set up a project/branch for the Drupal Core code, as described above, or (b) you can set up a "reference branch" that will make Drupal Core functions turn into links to api.drupal.org. To set up a reference branch, go to the "Reference Branches" tab in the API module admin section, (admin/config/development/api/php_branches), and click "Add new API reference branch" (admin/config/development/api/php_branches/new_api). The help under the fields should get you going... You will need to set up one of these for each core compatibility on your site, and during the next cron run, it will be updated to make the links.
  • You might want to turn off the "poor man's cron" functionality that is turned on by default in Drupal 7, because API cron jobs can take quite a while, and it might interfere with page loads. You can do that at path admin/config/system/cron (the "run cron every" setting). Of course, you'll need to set up an external cron job if you do that.
  • Use the steps above to create repositories, projects, and branches for Drupal 6, Drupal 8, contributed modules, etc.
  • By default, Drupal runs queued jobs during cron runs (the API module uses the Drupal queue for all of its branch updates and file parsing). As an alternative (or in addition), you might look into one of these contributed modules for queue management:
    Advanced queue
    Queue UI
    Drush Queue
  • The API module has Views integration, and as of mid-January 2013, Views are used to generate many of the listing pages in the API module. You can modify (carefully!) the default Views provided by the API module, or create your own pages using Views. Keep in mind that you may need to use Relationships to display some types of information.

Upgrading from Drupal 6

If you want to update an existing Drupal 6 API site to Drupal 7, it should work just like updating any other Drupal 6 site to Drupal 7. Here are a few notes about the specific contributed modules (besides what is in the Step 1 installation instructions above):

  • You will need to update the API module to version 6.x-1.9, and run update.php to get all the database updates, before attempting to upgrade to the Drupal 7 version. If you were running an old version of API (1.6 or earlier), read the release notes for version 1.7 about needing Drupal Queue.
  • The Drupal 6 version of API required the Grammar Parser module to be installed as a module. The Drupal 7 version requires it to be installed as a library. So you'll need to disable the module, then move the grammar_parser directory from sites/all/modules to sites/all/libraries. Or better yet, delete the old version and download the latest Grammar Parser files into sites/all/libraries.
  • The Drupal 6 version of API required the Drupal Queue module. This functionality is in core in Drupal 7, so you can just disable, uninstall, and delete that module before updating to Drupal 7.

Help improve this page

Page status: Deprecated

You can: