2024 State of SaaS APIs: URLs

April 26, 2024

Even though they're a key part of APIs, URLs are often ignored when discussing them. In this article — the second in our series based on our 2024 State of SaaS APIs report — we'll take a closer look at URLs.

Resources and URLs

A web resource is anything that is accessible via or connected to the web.

In the web's early days, the term "web resources" referred only to web pages and downloadable files, including the web page you're reading right now. Today, it refers to any physical, digital, or abstract thing that can be identified using a uniform resource locator (URL). When talking about APIs, we often shorten  "web resource" to "resource."

A uniform resource locator or URL is a string that specifies:

• The location of a resource (hence the name) on a network
• How you can obtain or perform an action on that resource

Most users understand URLs and the location of a web page and often refer to them as "web addresses." While not technically correct, it's close enough for everyday conversation. It doesn't help that the text field for entering URLs into a browser and displaying the current page's URL is called the "address bar."

In the context of APIs, URLs uniquely identify resources managed by the API, where the term "resource" could be anything the API provides access to, which is usually data or a method or function to perform an action on that data.

Structure of a URL

URLs have this general structure:

1. The scheme tells the server which protocol to use when serving the resource. Most APIs will use https (hypertext transfer protocol secure) as the scheme, which encrypts communication between the API and the client application calling it.
2. Subdomains are optional extensions to a domain name used to organize a website into different sections or determine which resources should be served. The www subdomain used to be mandatory, and it specifies that the resources served under that subdomain are served using the HTTP protocol.
3. People generally consider the second-level domain to be the first part of the website's domain name. It's usually the name of the organization, product, or person represented by the website. In the URL example.com, example is the second-level domain.
4. People generally consider the top-level domain (often shortened to TLD) to be the second part of the website's domain name. Top-level domains are a key part of the internet's domain name system hierarchy. In the URL example.com, .com is the top-level domain.
5. Every domain name is eventually translated into an IP address, and every IP address has 65,536 ports, which are communications channels assigned for specific services, such as HTTPS communications (port 443, over which most API communications will take place) and HTTP communications (port 80). If you're using the default port for a service, you don't have to specify the port number in a URL.
6. The path is the location of the resource on the server, expressed in the same way as a filepath on your own computer, with forward-slashes (the / character) specifying subdirectories.
7. The query is the portion of a URL for optional parameters. Placed after the end of the filepath portion of the URL and delineated by the ? character, it's a collection of key-value pairs separated by & characters. In the URL in the diagram above, the query is parm1=val1&parm2=val2, which specifies that the first parameter is parm1 and its value is val1 and that the second parameter is parm2 and its value is val2.

Endpoints and URL types in APIs

Each resource in an API has an endpoint: a specific corresponding URL that client applications — applications that use the API — can use to access it.

There is no formal standard for URLs used for API endpoints, but most API providers agree on a few informal ones, which are listed below:

1. Static base URLs: A static base URL is a fixed URL that serves as the root address for accessing the API. It does not change across different customers or users of the API.
2. Custom domain/subdomain-based URLs: Custom domain or subdomain-based URLs allow the base URL of the API to be customized for individual customers or users, often using their domain name. For example, if a company whose domain is example.com provided a custom subdomain for a company called "HypothetiCorp," they might provide this custom subdomain-based name for their use: hypotheticorp.example.com.
3. Versioned URLs: As a service evolves, so will the functionality and data it provides. This often leads to changes to the API, which will need to provide different URLs for new or updated functionality. One way APIs do this is by creating new URLs that use version numbers as part of the path. For example, a function that returned a list of customers at this endpoint — https://example.com/customers — might need to be revised. To preserve backward compatibility, the API provider might put the revised version at this URL: https://example.com/v2/customers. This approach keeps both versions available to clients and place the revised function in a URL that clearly marks it as version 2.

URL Usage

Static base URL at 93% is the most popular and widely used API URL. This indicates most APIs utilize a consistent and unchanging base URL for accessing their resources. Those URLs that are customer or tenant specific potentially offer more security, but are harder to implement as an application needs to ask the end-user to retrieve it.

72% of APIs have versioned URLs. Versioning in a URL is key to advanced API design, ensuring backward compatibility, clear communication, and secure, targeted updates without disrupting current users. It facilitates parallel development and planned upgrades, allowing for a clear deprecation path and client-controlled adaptation.

To learn more about API design or the stats referenced in this article, download the 2024 State of SaaS APIs.