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.
