Web Addresses and API Endpoints

Just as your home has a physical address that tells others how to find you, every resource on the Web has a “Uniform Resource Locator” or URL that tells browsers and applications how to locate and retrieve it.

Technically, every web server has an IP address, a unique numerical label assigned to every device connected to a computer network, like 192.0.2.1, and you could access websites using these numbers directly. But imagine trying to remember that Amazon is at 98.87.170.71 and Google is at 142.251.45.206. URLs use human-friendly domain names like amazon.comandgoogle.com` so we do not have to remember IP addresses.

Just as a website has a URL, a web API can be located at a URL. On a website, a URL might point to a web page. In an API, it identifies an endpoint where a client can request data (or an action). Take a weather forecasting site as an example. https://weather.example/ may take you to its home page, while https://api.weather.example/ may take you to the API home page. The API may have endpoints like https://api.weather.example/cities for the list of cities it covers, and https://api.weather.example/cities/baltimore for the weather forecast for Baltimore.

Let’s explore the anatomy of a URL and how it is used to locate resources on the Web, including API endpoints.

The https part is the scheme, which tells the browser or application to use the HTTPS protocol to communicate with the server. This is the HTTP protocol we discussed in the previous section, with one addition. The “S” at the end of HTTPS stands for “secure,” which means the communication is encrypted so that no one can read it while it is in transit. There are other schemes, such as ftps for secure file transfer and mailto for email.

The api.weather.example part is the domain name, which identifies the server hosting the resource. The .example is a made-up top-level domain name that I am using for examples. In real life, you will see .com, .org, .edu, and other top-level domain names. The weather part is the name that identifies the organization that owns the server. The organization must buy a domain name from a domain registrar accredited by the Internet Corporation for Assigned Names and Numbers (ICANN). The api part is a subdomain, which identifies one part of what the organization runs. The organization can create as many subdomains as it wants, and it can use them to organize its systems and resources. Historically, the www subdomain was used for web pages, so www.weather.example would be the organization’s website, while api.weather.example would be its API.

The /cities/baltimore part is the path, which specifies the location of the resource on that server. The path is hierarchical, like a file system. The first part, /cities, identifies the collection of cities the API covers. The second part, /baltimore, identifies the specific city for which the client wants the forecast. The server uses the path to determine which resource to return to the client.

We may also see query parameters, which are additional pieces of information sent to the server. For example, https://api.weather.example/forecast?city=baltimore&days=3 has two query parameters. The first, city=baltimore, tells the server which city the client wants the forecast for. The second, days=3, tells the server to return the forecast for the next three days. Query parameters are introduced by a ? and multiple parameters are separated by &.