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. - https://github.com/opensearch-project/opensearch-api-specification/issues/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. - https://github.com/opensearch-project/opensearch-api-specification/issues/74
• [ ] Publish OpenAPI specs. - https://github.com/opensearch-project/opensearch-api-specification/issues/34
• [ ] API spec versioning. - https://github.com/opensearch-project/opensearch-api-specification/issues/84
• [ ] Deprecate the rest-api-spec in OpenSearch. - https://github.com/opensearch-project/OpenSearch/issues/4027
• [ ] Write client generators for different programming language clients to generate all or selected new/missing APIs. - https://github.com/opensearch-project/opensearch-clients/issues/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. - https://github.com/opensearch-project/opensearch-api-specification/issues/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. - https://github.com/opensearch-project/opensearch-clients/issues/55

Client Generators

• [ ] Java - https://github.com/opensearch-project/opensearch-java/issues/284
• [ ] Ruby - https://github.com/opensearch-project/opensearch-ruby/issues/139
• [ ] Python - https://github.com/opensearch-project/opensearch-py/issues/348
• [ ] Go - https://github.com/opensearch-project/opensearch-go/issues/284

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

[dblock]

I opened https://github.com/opensearch-project/opensearch-api-specification/issues/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.