To demonstrate concepts in our book on REST API design and implementation, we used simple example APIs that accompany the reader in different chapters. The first one of them is the Product API, exposing a REST resource named "products". A product is an entity that any software engineer can imagine without a lot of explanation.
But a "simple" entity that is good to describe various technical aspects of APIs can be actually quite dangerous in real-world software projects. Just try to put yourself in the shoes of a tester or a business user. What exactly should the "products" endpoint return? Should it include discontinued products? Or should it only return the products currently in stock?
APIs are often used to connect services or subsystems that have different (bounded) contexts and are developed by separate teams. The developers should not forget to negotiate the exact meaning (semantics) of the data. An OpenAPI specification, although very useful, is not sufficient as it only defines the syntax.
Naming things is one of the hardest things in software engineering. Choosing the right name for a program variable or function can prevent many misinterpretations. The same goes for APIs.
When in doubt, I usually prefer more specific names (e.g. productsInStock) or sometimes even artificial names (productsFromBizRule345). It is safer to have multiple names for the same thing than having multiple things for one name. Make sure the name is mappable to the business domain. A name is not good if you need to look at the code implementation to understand its meaning.
This is important to remember if you decide to use a "modular monolith" architecture. Calling functions of a programming language within one program has definitely many advantages compared to invoking remote APIs. But these APIs can also cross business context or team boundaries, so make sure they are not coupled to the implementation.
Lastly, I'll mention the increased use of generative AI in software development. LLMs are trained on text and the result of a generative AI is greatly improved by providing it with a good context. Using domain-driven, specific, unambiguous names and clear text descriptions for your API items will help the AI models help us more.