OpenSearch Spec and Client Generation Roadmap

[VachaShah]

This issue describes a roadmap for generating API specs and clients for OpenSearch. Each issue linked has a detailed description of the part.

• Convert legacy rest-api-spec in OpenSearch to Smithy models. - [PROPOSAL] Evolving the API Spec repo opensearch-api-specification#80
• Test the generated Smithy models for accuracy with the server with the current test framework in the opensearch-api-specification repo.
• Explore the use of already existing yml test cases[1] to test the Smithy models.
• Implement workflow to auto-update specs when a change is made to Smithy models. - [PROPOSAL] Build architecture for spec and client generation opensearch-api-specification#74
• Publish OpenAPI specs. - [PROPOSAL] Add a workflow that publishes this spec in OpenAPI format  opensearch-api-specification#34
• API spec versioning. - [PROPOSAL] Publish versioned API specs opensearch-api-specification#84
• Deprecate the rest-api-spec in OpenSearch. - Delete unused parts of rest-api-spec OpenSearch#4027
• Write client generators for different programming language clients to generate all or selected new/missing APIs. - [PROPOSAL] Use API specification to generate clients #19
• With the flood of APIs generated in the clients, explore the possibility of an automated test case generation with a common test case data. For example, if the test data resides in opensearch-api-specification repo, use this test data in all clients to test against the server for those APIs. This will help get test coverage with reduced manual effort. See if yml files from [1] can be used similar to the rust client.
• Update the clients when a change is made to the Smithy models. - [PROPOSAL] Build architecture for spec and client generation opensearch-api-specification#74
• Implement continuous integration framework for generated clients.
• Modify client generators to generate existing APIs in clients and maintain backwards compatibility.
• Extensions support for clients. - [PROPOSAL] Client Support For Extensions #55

Client Generators

• Java - [PROPOSAL] Experiment with using Smithy API spec to generate missing APIs opensearch-java#284
• Ruby - [FEATURE] Generate API code from OpenSearch API Spec opensearch-ruby#139
• Python - [FEATURE] Enhance the existing code generator to use the OpenAPI spec as the input format opensearch-py#348
• Go - [FEATURE] Generate API code from OpenSearch API Spec opensearch-go#284

[1] - https://github.com/opensearch-project/OpenSearch/tree/main/rest-api-spec/src/main/resources/rest-api-spec/test

[dblock]

I opened opensearch-project/opensearch-api-specification#84 for API versioning. I think we may want to resolve that one earlier than later in order to enable clients to have a strong schema against various versions and flavors of OpenSearch.

[VachaShah]

I opened opensearch-project/opensearch-api-specification#84 for API versioning. I think we may want to resolve that one earlier than later in order to enable clients to have a strong schema against various versions and flavors of OpenSearch.

Makes sense. Moving it up the list.

[dblock]

Closing this in favor of #19 which encompasses most work here.