Descriptive parameter names

Use specific, descriptive parameter names for API resources rather than generic identifiers. Parameter names should clearly indicate the resource type they refer to by using namespaced identifiers (e.g., userId instead of id). This improves API readability, reduces ambiguity in code, and prevents confusion when multiple resource types are used in the same context.

When designing API endpoints:

• Prefix ID parameters with the resource name (e.g., credentialId, workflowId)
• Maintain consistent naming patterns across similar resources
• Document parameter naming conventions for your API

For example, instead of:

# In users parameter schema
name: id

Use:

# In users parameter schema
name: userId

This practice is especially important in OpenAPI specifications where parameter names directly impact client implementations. Changing parameter names after an API is published can break clients and require comprehensive updates across endpoint definitions, routes, controllers, and documentation.