dapr
Proposal on some high level things
Hi guys, before diving into the details, I think we need to agree on some high-level things, so I wrote this proposal to see your opinions.
Q: What problems does api spec solve?
I personally think there are two aspects:
- Technical side: make the current dapr api cross transport protocol,like the CloudEvent spec.
For example,we can define a "proto" for Dapr http 1.1 API using OpenAPI or AsyncAPI,so that we can leverage the tools of OpenAPI and even develop a "Dapr edge" for edge computing.
For more details, you can refer to the discussion https://github.com/dapr/dapr/issues/2817#issuecomment-794447509
We can define api spec for more transport protocals in the future, maybe including api for in-process invocation.
Besides, I am considering whether to define "an API spec for metadata". Since currently different dapr components have different metadata fields,and these fields will hurt portability, I think we can define a specification for metadata fields. I put this idea here to see everyone's opinion.
- Marketing side: make the dapr API an industry standard so that it can be more widely adopted by more vendors and developers.
Can we attract more cloud vendors to offer dapr hosting services, not only Azure? Can we attract more developers to build software around this industry standard, like kubernetes defined those neutral APIs and won developers’ hearts and minds?
How to define spec for different protocals?
https://github.com/dapr/dapr/issues/2817#issuecomment-784754684
We can have the spec to be independent of protocol. And then add sections for the recommended implementation in grpc, http1.1 and http2.
Similar to how CloudEvent has a spec and then describes how to implement the spec in JSON, Avro, etc.
— Artur Souza
Roadmap
We can devide the work into phases:
Phase 1: Write some specs for the existing v1 protos and v1 REST APIs.
In this phase:
- We will not modify any existing dapr api. Compatibility is necessary.
- We build a mechanism for designing api specs.
Phase 2: Once we have a mechanism, if someone raises a feature request in the runtime repository to modify or add an api, the sig-api will be responsible for discussing whether the change should be made and how.
Phase 3: Once the specs for both protos and REST APIs are ready, we can discuss the next step which is possibly renaming or moving to a separate org like OpenXXX. In this phase, we try to promote the dapr api spec to become the industry standard.
Where to start
We can start from the OpenAPI spec for state store API proposed by @wcs1only
@seeflood thanks for the proposal. We discussed this in STC and there's agreement regarding phase 1, which is to create the spec for the existing APIs.
As for phase 2, the decision about changes of APIs should still reside with maintainers, so I would change this to get input and recommendations from the SIG rather than final approval.
Phase 3 makes sense to start discussions around the name and location of the APIs.
@yaron2 lgtm.
As for phase 2, the decision about changes of APIs should still reside with maintainers, so I would change this to get input and recommendations from the SIG rather than final approval.
ok. Actually I just want the sig-api members to fully participant in the API design process, such as participating in discussions, giving everyone's opinion. It is reasonable to let the maintainer make the final decision