[Security Solution] Generate `.http` files

maximpn commented 2 months ago

Epic: https://github.com/elastic/security-team/issues/9723 (internal)

Summary

It'd be nice to extend OpenAPI code (kbn-openapi-generator package) generator to generate .http files. Such files allow to defined and send HTTP requests with a variety of tools.

Details

What is an `.http` file?

.http files allow you to define and send HTTP requests with support directly from within visual studio, VSCode and etc. You can find more information in the following sources

VSCode supports .http files via httpYac extension.

Simple .http files with an environment were added in a PR.

What should be done?

OpenAPI generator might easily generate template .http files. Engineers will be able to use such files with a tool of their choice to send requires to Kibana API for debugging, developing, SDHing and etc. The area of use could be defined by an environment.

Obviously code generator isn't able to cover all use cases. Engineers will have to provide data manually.

Tasks

[ ] Define a usage model (what should be generated and what should be manually provided, what environment should be used and should code generator generate them)
[ ] Implement the functionality according to the usage model
[ ] Update the documentation

elasticmachine commented 2 months ago

Pinging @elastic/security-detections-response (Team:Detections and Resp)

elasticmachine commented 2 months ago

Pinging @elastic/security-solution (Team: SecuritySolution)

elasticmachine commented 2 months ago

Pinging @elastic/security-detection-rule-management (Team:Detection Rule Management)

spong commented 2 months ago

Thanks for capturing this @maximpn! In introducing .http support in https://github.com/elastic/kibana/pull/186566, my goal was to trial an approach to streamlining API development, with the hope being that maybe we could generate these .http files and a base set of mocks, and then use said mocks in these client files and also in our API integration tests.

Turns out (at least the IntelliJ Platform integration) doesn't support TypeScript imports, and so mocks would need to be stored as either raw JSON or in JavaScript files... 😔 This is not great as it would be ideal to keep type safety support in our defined mocks.

I've created this issue requesting support for importing TypeScript files.

If this cannot be supported by all cross-platform clients, I would say this is a detractor to this approach and we may want to explore other ways of streamlining these API creation workflows.

elastic / kibana