[Proposal] OpenAPI specifications for dashboards APIs

[BionIT]

Overview

In the past few years, we have received many feedback from the community about the gap of documentation, the confusion in using our APIs. The proposal aims to come up with a solution to enable a standard way to define and document our APIs, starting with saved objects APIs which have been mentioned in several past discussions and not well documented.

Related discussions/issues:
#1647
opensearch-project/documentation-website#3799
#1700
#1723

Why OpenAPI

The OpenAPI (https://swagger.io/specification/) Specification defines a standard, language-agnostic interface to the HTTP RESTful APIs which allows both humans and computers to discover and understand the functionalities provided by the service without having to read through the source code or lengthy documentation. When properly defined, a consumer of the API can understand and interact with the service with a minimal amount of efforts. The OpenAPI definition file can be in the YAML or JSON format.

When generated, OpenAPI definition can then be used by documentation generation tools to display the API such as swagger UI, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

The benefits that came out of the box and would help both developers and users of dashboards APIs.

Saved object API

Being the fundamental of OpenSearch Dashboards' functionality, Saved object APIs allows various operations (CRUDL) to manage the objects including dashboards, visualizations, saved searches, and more. However, without looking through the source code or poking around to find examples, it is pretty difficult for people to understand how the saved object API works. Using saved object as example would help reduce the gap as well as to demonstrate the benefits.

With more APIs being introduced to the dashboards, we can use the spec of saved object as example to ensure new APIs get documented following the same standards.

Goal

Dashboards have several APIs, and we propose to start with saved object APIs

• Create specification for Get and Create saved objects API (Add OpenAPI specification for get and create saved object APIs  #6799)
• Add example in create API for create index pattern, vega visualization, dashboards
• Create specification for bulk_get and find API and add example for get/find dashboards
• Create specification for import, export, remove import errors saved object APIs and add example for import and export
• Create specification for Delete, Update, Migrate saved objects APIs
• Create specification for bulk_create, bulk_update saved object APIs
• Create tool to easily bundle the specifications
• Add linter and validation for the specification

Example

https://bionit.github.io/#/Saved%20Objects

[seraphjiang]

Thanks @BionIT , like the idea to use swagger to generate api doc

• Could we list all existing saved object api so we could track progress
• could we have use one api to create an example

[ashwin-pc]

@BionIT Love the idea! Have you looked into the existing API doc generation tool? yarn docs:acceptApiChanges . This documents Plugin API's though but id like to have one consolidated tool rather than two if possible.

[BionIT]

Thanks @ashwin-pc! Yeah, I looked at it which using api-documenter behind the scene to generate markdowns, it is different from what I am proposing here which is to provide API specification which explains how our dashboard rest API behaves and what to expect from the API in a standard format. It can work together with swagger UI.

[zengyan-amazon]

Thanks @BionIT ! It is a great idea to leverage Swagger to improve the discovery and integrity of OpenSearch Dashboards APIs!

[ashwin-pc]

Makes sense. Will this be an automated flow or do we have to track it manually? Also is there a reason you are limiting it to just saved objects? Sicne we have some other useful API's like the stats API that could benefit from this :)

[seraphjiang]

let's add sub tasks

• add example for creating visualization through saved object
• add example for creating dashboards through saved object
• add support build-in saved object type [viz, dashboards, index-pattern, datasource, workspace]
• add example for advanced settings