Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough

API Documentation and Developer Portals: common URL patterns

Parent Feed: 

As part of our research into content architecture best practices for Developer Portals, we’ve done a small scale investigation to evaluate what URLs are used by API companies.

We looked at a sample of 211 companies that had a Drupal site and an API integration module on Drupal.org. We found that one quarter of the examined companies (51 companies out of 211) had a dedicated section for their API documentation.

Our main goal was to determine what URL patterns are most frequently used by API providers. The pie chart below displays the most popular patterns; as indicated there was a large group of ‘other’, that could not be classified. Among the grouped patterns domain.com/api (7,84 %) and docs.domain.com/api (5,88 %) were the most frequently used.

One way to classify URL patterns is to see if they contain the main domain or a subdomain. We found that 68,6 % of the sites used a subdomain and 31,4 %, used the primary domain.

Most likely this is because companies want to make a distinction between the area of their website dedicated to developers (with a focus on simplicity and transparency), and the area dedicated to decision makers (with more emphasis on business value and product maturity).

Hosting your documentation on a subdomain can be a good idea if there is a clear separation between these two audiences for your product.

When choosing between different URL patterns, SEO will also play an important role. An API site can be easily identified by name if it contains keywords. This also makes it easier to show up in relevant search results.

Not too long ago URLs’ only real purpose was to request information from web servers. Today web services use SEO friendly URLs that contain path aliases, that help Search Engines classify the page content.

The table below encompasses the anatomy of a SEO friendly URL with some tips on creating a great URL.

Source: moz.com

This is the first article in a research series we are publishing about content architecture for API documentation and Developer Portals. Sign up below to get notified about future posts.

Subsribe now

*We will not publish, share, or sell your email address in any way.

Author: 
Original Post: 

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web