jon-whit
commented
9 months ago - [ ] todo: add protobuf doc to every protobuf message and field as appropriate.
- [ ] todo: add required field specifications and other protobuf annotations for OpenAPI generation
Description
Start the development branch for the
v2beta1protobuf API definitions for OpenFGA. This is to get things started with that new API development effort as we go into the new year.As we work through these changes in the scope of this PR, lets try to focus on a few guiding principles:
Well typed and strongly typed protobuf API contract - prefer objects over string encoded entities where you can (e.g.
Objectinstead ofstring object)Separation of input types vs output types and a clear definition of required vs non-required fields within them- this really helps other development in our tooling such as in the SDKs etc..
Think about the gRPC experience, not just the HTTP mapping - the protobuf API is the definitive source of truth. The HTTP API is derived off of it. When in doubt, the protobuf API should take precedence.
Give a shit about naming things - if you've had a beef with the API names, speak up and fight for the cause š
Encourage strong alignment with
buf lintlint style guidelines so that we have a standard - we shouldn't have to make exceptions regularly for our protobuf API linting behavior. Stick to the community standard of usingbuf lintand the default rules for it.Consider Google API Improvement Proposals (AIPs) as a good starting point for inspiration behind certain API changes and design - we don't have to copy Google API guidelines, but they've clearly given a lot of API experience some thought and since they are the primary driving force behind gRPC and RPC APIs in general, their guidelines are a good reference point for ideas of achieving certain design goals. In particular, consider the AIPs around standard methods.
A few notable changes to get started:
The new API has been designed with an emphasis on a strongly typed protobuf API. For example, instead of
string objectfields we have explicitObject objectfields.Userfields have been renamed toSubjectto avoid confusion with the often defined type nameuser.Subjectis a strongly typed entity that can be one_ofObject(a direct object),TypedWildcard(to represent the public wildcard), or aSubjectSet(to represent the set of subjects that expand to one or more concrete objects). ASubjectSetmodels Usersets in Zanzibar nomenclature.TupleKeyhas been more aptly namedRelationshipTuple- this coincides with our official documentation Concepts better (see Relationship Tuple)Userset, which previously represented a relation rewrite rule, has been refactored to a more aptly namedRelationRewriteand the model of it is much more uniform.The relations defined in an AuthorizationModel has changed from a direct
Userset rewritefield to a map of Relation structuresmap<string, Relation>. This will make things more uniform by far in all application code that deals with an AuthorizationModel structure and will more easily allow for indexing into the model's relation map to grab a particular relation.Relationnow uniformly represents a relation definition, and the constructs associated with it such as the type restrictions that apply to it etc..The
ReadChangesAPI has been renamed toWatchChangesand has been relocated to an auxillary gRPC service definitionWatchService. This will allow for a separate watch server to implement the WatchService and allow that service to be hosted and scaled independently of the mainOpenFGAServicewhich services Checks, ListObjects, etc.. The ability to serve and scale this service independently will be more important especially as we start building other features around changelog metadata such as the indexer andExpandedWatchChangesendpoints etc.. These workloads will be different and need not be served from the same server in general..References
Review Checklist
main