API naming conventions and code generation

Naming conventions play a crucial role in the quality of the SDK that you generate for your API. Here are some examples of naming conventions for a few API architectural styles:

• Plural nouns to represent REST resources, e.g., /articles.
• Use of HTTP verbs to access REST endpoints, e.g., POST /articles.
• Singular nouns to represent data types in GraphQL, e.g., Article.
• Use of verbs for GraphQL mutations, e.g., CreateArticle.
• Using the word “service” to identify gRPC services, e.g., ArticleService.
• Verb-noun structure to define event names in asynchronous APIs, e.g., ArticleCreated.

If you decide to follow a different structure—or don’t follow any structure at all—the SDK you generate will be harder to use by developers. As an example, the OpenAPI operationId attribute should be named in a way that works well across the programming languages that you want to support. The OpenAPI specification even recommends that:

Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.—OpenAPI specification 3.1.0 § Operation Object

So, it’s important to pay attention to how you’re naming things on your API so consumers have the best possible experience.