-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update protos based on revised concept names (#71)
* Clarify prerequisites in README * Correct headings in README * Add relations API protos based on revised concept names * Experiment with some additional updates - Updated service names to be globally unique per protobuf API best practices - TODO: Look at how service names are used in nginx routing (check with kwalsh) - Factored out object namespace per concepts - TODO: confirm what fields are optional in relation tuple filter and mark accordingly - I kept the VerbNoun format for method names for name, in order to comply with Buf.build lint rules - Kept SubjectReference as is; may revisit this per previous comments * Incorporate latest updates and docs * Fix very very very important newline at end of file * Add an API design README * Correct whitespace * Clarify method name conventions * Disambiguate Health service name also * Regenerate API and update code (#87) * Add underscores to java packages in proto files. (#89) --------- Co-authored-by: wscalf <[email protected]> Co-authored-by: Mark McLaughlin <[email protected]>
- Loading branch information
1 parent
5915c39
commit 4e08f39
Showing
34 changed files
with
2,607 additions
and
2,153 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,51 @@ | ||
# API Design | ||
|
||
API design should refer to the following style guides, in this order of precedence: | ||
|
||
- https://protobuf.dev/programming-guides/proto3/ | ||
- https://protobuf.dev/programming-guides/dos-donts/ | ||
- https://protobuf.dev/programming-guides/api | ||
- https://buf.build/docs/best-practices/style-guide | ||
- https://cloud.google.com/apis/design | ||
|
||
## Notes | ||
|
||
These are some specific call outs from the above docs which are useful or surprising in case you | ||
didn't spend the required time to go through all of those links. | ||
|
||
### Service names | ||
|
||
Service names should be globally disambiguated, even regardless of package, hence the inclusion of | ||
"Kessel" in the names (https://protobuf.dev/programming-guides/api/#service-name-globally-unique). | ||
|
||
### Comments | ||
|
||
Comment fields using Markdown (https://buf.build/docs/bsr/documentation#supported-formatting-syntax). | ||
|
||
### Method names | ||
|
||
These generally follow Google Cloud's guidance, with VerbNoun, in imperative mood, with a standard | ||
set of verbs. Custom method names are allowed outside of this. | ||
|
||
- https://cloud.google.com/apis/design/naming_convention#method_names | ||
- https://cloud.google.com/apis/design/standard_methods | ||
|
||
Note that "List" uses paged messages, _not_ streams, | ||
so "List" should be avoided for methods with streaming responses. | ||
|
||
It does not appear there is any other convention for methods with streaming responses, | ||
[based on querying all of GCP's APIs][1]. | ||
|
||
[1]: https://github.com/search?q=repo:googleapis/googleapis+%22returns+(stream+%22+language:%22Protocol+Buffer%22&type=code&p=1 | ||
|
||
## Troubleshooting | ||
|
||
### Using VSCode proto extension and seeing import errors? | ||
|
||
Add this to your settings.json: | ||
|
||
``` | ||
"protoc": { | ||
"options": ["--proto_path=api", "--proto_path=third_party"] | ||
} | ||
``` |
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.