Consistent OpenAPI paths, parameters, and operationId naming convention

[paulespinosa]

Overview

The OpenAPI spec (api/openapi_server/openapi/openapi.yaml) contains inconsistent naming conventions.

To promote consistent and predictable naming, align on a naming convention for OpenAPI parts (paths, parameters, and operationId and update the OpenAPI definitions, API code, and App code.

Across all naming conventions for parts, they should be:

• simple
• intuitive
• consistent

OpenAPI Paths

The OpenAPI spec uses at least two naming conventions for paths: mixedCase and snake_case. The preference is to use all lowercase with hyphen separating words (e.g. /service-providers/).

OpenAPI and Python parameters

The OpenAPI parameters and Python function definition parameters should have consistent naming, preferably Python PEP8 snake_case.

• the parameters on HomeUniteUs/api/openapi_server/openapi/parameters/_index.yaml
• the parameters on paths HomeUniteUs/api/openapi_server/openapi/openapi.yaml
• the parameters on controller definitions

Documentation should be added about Python function definitions with parameters using Python built-in names should append an underscore to the paramater name. Connexion parameter handling

For example: def example_func(filter_): because filter is a Python built-in name for the filter() function.

OpenAPI operationId

The OpenAPI operationId should have consistent and predictable naming. The preference is to use Python PEP8 snake_case because operationId represents Python functions.

Action Items

• [ ] Establish naming conventions (there will be different conventions used for paths, parameters, and operationIds)
• [ ] Update API: OpenAPI spec and Python code
• [ ] Update App: Calls to the API
• [ ] Tests
• [ ] Document naming conventions in README

Resources/Instructions

Changes to paths in the API need corresponding changes to the app.

Initial conversation about naming conventions: https://github.com/hackforla/HomeUniteUs/pull/543#discussion_r1273005912 connexion documentation about parameter names: https://connexion.readthedocs.io/en/stable/routing.html#parameter-name-sanitation Python PEP 8 function and variable naming: https://peps.python.org/pep-0008/#function-and-variable-names

[agosmou]

Hey @paulespinosa Paul, let me know what you think of the below. I was getting errors because my controller had parameter email but my openAPI .yaml parameters were UserEmail.

• Error:
  • TypeError: get_user_by_email() got an unexpected keyword argument 'user_email'

Connexion was converting my naming convention to snake_case and giving me issues with my controller.

Thus, the parameters should have consistent naming, preferably snake_case.

1. the parameters on HomeUniteUs/api/openapi_server/openapi/parameters/_index.yaml
2. the parameters on paths HomeUniteUs/api/openapi_server/openapi/openapi.yaml
3. the parameters on controller definitions

Connexion converts CamelCase to snake_case on requests so it's best to stay consistent

[paulespinosa]

@agosmou Do you recommend that the OpenAPI parameters be written as snake case? For example: /serviceProviders/{providerId}: -> /service-providers/{provider_id}: -> def get_service_provider_by_id(provider_id: int) -> Response:

Should there be a documented rule to append underscore to parameters that match Python built-ins? For example: /example-endpoint/{filter} -> def example_view_function(filter_):

[agosmou]

@agosmou Do you recommend that the OpenAPI parameters be written as snake case? For example: /serviceProviders/{providerId}: -> /service-providers/{provider_id}: -> def get_service_provider_by_id(provider_id: int) -> Response:

I feel this would be a safe approach - it could prevent future bugs.

Should there be a documented rule to append underscore to parameters that match Python built-ins? For example: /example-endpoint/{filter} -> def example_view_function(filter_):

I'll do some testing to see if the above provides a layer of safety for us.

[tylerthome]

Also related to #637 and completed, pending a once-over by dev leads before finalize