We often talk about API design here at Nordic APIs and best practices to follow. One of those best practices is clear and consistent naming conventions throughout the API — from endpoint resources and URIs to fields and parameters. Naming is often overlooked in API design, leading to a poor experience for consumers.

Imagine the confusion for developers when they encounter an API where every endpoint and resource uses a different naming convention. Some have camelCase and underscores for compound words, while others have lowercase letters and hyphens. Some resources have jargon or word variants that some users may not know. And none of the URIs include versioning, which impacts backward compatibility.

Inconsistent naming can lead to poor developer experiences and reduce overall API adoption. In fact, Postman’s 2025 State of the API Report says that “certain practices make APIs more consumable by both humans and machines.” These practices include consistent naming conventions. Predictable naming is a core strategy for making APIs consumable for AI agents as well. This is because AI agents rely on semantic clues and recognizable patterns to infer the intent and structure of API calls.

Considering the importance of consistent naming, we’re highlighting four popular APIs that use effective naming conventions. We chose these APIs based on the naming conventions of components, such as endpoints, URIs, resources, and parameters. We also looked at the structure of URIs. The list is in alphabetical order.

Amadeus Hotel List API

The Amadeus Hotel List API is a great example of good API naming practices.

The Amadeus Hotel List API is one of many Self-Service Travel APIs offered by Amadeus. These APIs provide applications with access to essential travel information and capabilities. Categories include flights, hotels, destination experiences, market insights, and cars and transfers. The company also provides Enterprise APIs that offer comprehensive travel content and a wide range of features. The Hotel List API’s three endpoints (by-city, by-geocode, by-hotels) use clear and understandable naming conventions.

API Call Examples (Test Endpoints)

Return a list of hotels for a specific city (London):

https://test.api.amadeus.com/v1/reference-data/locations/hotels/by-city?cityCode=LON

Return a list of hotels for a city using geocoding (Sydney):

https://test.api.amadeus.com/v1/reference-data/locations/hotels/by-geocode?latitude=33.8727&longitude=151.2057

Search hotels using a unique Amadeus hotel Id (Acropolis Hotel Paris Boulogne):

https://test.api.amadeus.com/v1/reference-data/locations/hotels/by-hotels?hotelIds=ACPARH29

Search for Marriott hotels in Paris that allow pets (EM for Marriott):

https://test.api.amadeus.com/v1/reference-data/locations/hotels/by-city?cityCode=PAR&chainCodes=EM&amenities=PETS_ALLOWED

The developers at Amadeus follow consistent naming practices for all their Self-Service Travel APIs. For example, the Hotel List API uses kebab case for resource names and paths, making them easier for API consumers to read and understand.

All the endpoints include versioning, which helps the Amadeus team maintain backwards compatibility and prevent breaking changes that impact users.

Data fields and query parameters use camelCase or an all-caps version of snake case. Kebab case is not commonly used for these components because it’s not compatible with most programming languages.

OpenWeatherMap API

The OpenWeatherMap API is well-designed and has effective naming conventions.

One of the most popular weather APIs is the OpenWeatherMap API, which provides a wealth of weather information for locations all over the world. The API is provided as a “pay as you call” service (One Call API 3.0) and as professional collections. The collections include current weather data and hourly forecasts, historical weather data, and weather maps. The company also offers specialty APIs, such as the Solar Irradiance API, which provides solar data based on a specified location. You can see the consistency in naming in various API calls.

API Call Examples

Get current weather data for a specific location (Tokyo, Japan):

https://api.openweathermap.org/data/2.5/weather?lat=35.6764&lon=139.6500&appid={API key}

Get hourly forecast data for a specific location (Paris, France):

https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=48.8575&lon=2.3514&appid={API key}

Get current air pollution data for a specific location (Los Angeles, CA):

http://api.openweathermap.org/data/2.5/air_pollution?lat=34.0549&lon=118.2426&appid={API key}

Get hourly historical weather data for a specific location (Rome, Italy):

https://history.openweathermap.org/data/2.5/history/city?lat=41.8967&lon=-12.4822&appid={API key}

The developers at OpenWeatherMap have used simple, intuitive names throughout. The API does not include weather jargon that some consumers may not know. When you see the names “forecast” and “hourly” in the URI, you know that you’ll get an hourly weather forecast for a specified location.

They have included versioning in the URI, which helps developers immediately see which version of the API is being called and helps them track changes. The forward slashes show the hierarchy of collections and individual resources, which helps make the API more intuitive. The way they have named and structured resources and URIs makes it easier for consumers to understand what each API call does.

Spotify Web API

The Spotify API is well-structured with thoughtful naming that allows consumers to easily understand what each endpoint does.

Spotify is considered the world’s most popular audio and music streaming subscription service, so it makes sense that many developers would want to integrate the Spotify Web API with their applications. The API lets developers create applications that interact with the Spotify service, taking actions such as managing playlists and controlling playback.

API Call Examples

Get information for a single album from the Spotify catalog for the Canadian market:

https://api.spotify.com/v1/albums/{id}&market=CA

Get the current user’s top artists based on measured user behavior (calculated affinity):

https://api.spotify.com/v1/me/top/artists&limit=20

Get the current playback state for the user:

https://api.spotify.com/v1/me/player

Get an artist’s top tracks by country (Canadian market):

https://api.spotify.com/v1/artists/{id}/top-tracks&market=CA

Spotify’s Web API has numerous endpoints and resources, all of which follow clear and consistent naming practices. The development team uses simple naming for singleton resources and plural nouns for collections, which makes them more intuitive.

The team has avoided including special characters in URIs, e.g., top-tracks versus top%20tracks. Adding special characters is considered bad practice because some consumers may not have access to them, causing confusion. They have also kept the URIs clean by NOT adding a trailing forward slash to the end of them — it’s not necessary and considered poor practice.

Stripe API

Effective naming goes a long way, especially when an API is as big as Stripe’s.

Stripe’s API provides numerous capabilities — from global payments and revenue automation to money management and identity verification. It has many groups of resources (collections) that you can search through and list. Some of the requests involve referencing previous queries created with Stripe’s Search Query Language.

API Call Examples

Search for invoices:

https://api.stripe.com/v1/invoices/search&limit=100

Get a list of invoices based on status:

https://api.stripe.com/v1/invoices&status=paid

Return a list of files accessible by your account and based on purpose:

https://api.stripe.com/v1/files&purpose=account_requirement

Get a list of all checkout sessions:

https://api.stripe.com/v1/checkout/sessions

Developers love the Stripe API for many reasons. It comes with excellent API documentation and SDKs in a variety of programming languages. Like the other APIs mentioned above, Stripe’s API has effective naming — plural nouns for collections, understandable names for resources, versioning, forward slashes for hierarchy, and so on.

Stripe provides a massive API organized by resource categories. However, the company’s development team has implemented a naming strategy that helps consumers understand what each endpoint and resource does.

Improve the Developer Experience with Great Naming Conventions

API providers should establish style guides for every API, and those guides should include consistent naming conventions. Without some guidance, every developer involved in API design will independently decide what naming conventions to use. This will lead to messy and confusing endpoints, resources, URIs, and so on. However, when developers are all on the same page, you get consistent naming that helps create a better experience for human and AI agent consumers alike.