From 662f81b4a87f59bb8bd319ad692d01f04d0809b7 Mon Sep 17 00:00:00 2001 From: Mario Izquierdo Date: Sun, 13 Sep 2020 18:37:23 -0700 Subject: [PATCH 1/2] Mention Protobuf Style Guides on the v7 protocol --- docs/spec_v7.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/spec_v7.md b/docs/spec_v7.md index 1b698596..728a4464 100644 --- a/docs/spec_v7.md +++ b/docs/spec_v7.md @@ -53,6 +53,17 @@ the following components. * **Method** is the proto `rpc` name for an API method. For example, `CreateEvent`. +The package, service and method names are taken from the proto file +definition. The [Protobuf spec](https://developers.google.com/protocol-buffers/docs/reference/proto3-spec#identifiers) +allows to use CamelCased and underscored_names. However, Twirp +implementations usually need to map Service and Method names to +their specific naming conventions, which may cause naming collisions. +For example, Go requires exported variables to start with a capital, +so the names `MyMethod` and `myMethod` will map to the same interface method. +To avoid this problem, Twirp implementations should expect and fully support +names that follow the [Protobuf Style Guide](https://developers.google.com/protocol-buffers/docs/style#services), +in particular, Service and Method names that are CamelCased (with an initial capital). + ### Requests Twirp always uses HTTP POST method to send requests, because it From 07d35cf426e0e1e69015db6f8f7e594db5a58b93 Mon Sep 17 00:00:00 2001 From: Mario Izquierdo Date: Thu, 24 Sep 2020 22:28:47 -0700 Subject: [PATCH 2/2] Improve docs on routing, leave spec clean --- docs/routing.md | 4 +--- docs/spec_v7.md | 11 ----------- 2 files changed, 1 insertion(+), 14 deletions(-) diff --git a/docs/routing.md b/docs/routing.md index f8b661a1..36581794 100644 --- a/docs/routing.md +++ b/docs/routing.md @@ -31,9 +31,7 @@ More details on the [protocol specification](spec_v7.md). #### Naming Style -Please follow the [Protocol Buffers Style Guide](https://developers.google.com/protocol-buffers/docs/style#services). In particular, the `` and `` names should be CamelCased (with an initial capital). - -The [official Go implementation](https://github.com/twitchtv/twirp) differs in behavior from what is described in the [protocol specification](spec_v7.md). The routes are modified to be CamelCase instead of using the exact from the proto file definition, so URL paths generated by Go clients may differ from paths generated by other languages. This issue is discussed in [#244](https://github.com/twitchtv/twirp/issues/244), and is easily avoided by following the Protocol Buffers Style Guide on your proto files. +For maximum compatibility, please follow the [Protocol Buffers Style Guide](https://developers.google.com/protocol-buffers/docs/style#services). In particular, the `` and `` names should be CamelCased (with an initial capital). This will ensure cross-language compatibility and prevent name collisions (e.g. `myMethod` and `my_method` would both map to `MyMethod`, causing a compile time error in some languages like Go). ### Content-Type Header (json or protobuf) diff --git a/docs/spec_v7.md b/docs/spec_v7.md index 5f72f005..46f9f62e 100644 --- a/docs/spec_v7.md +++ b/docs/spec_v7.md @@ -53,17 +53,6 @@ the following components. * **Method** is the proto `rpc` name for an API method. For example, `CreateEvent`. -The package, service and method names are taken from the proto file -definition. The [Protobuf spec](https://developers.google.com/protocol-buffers/docs/reference/proto3-spec#identifiers) -allows to use CamelCased and underscored_names. However, Twirp -implementations usually need to map Service and Method names to -their specific naming conventions, which may cause naming collisions. -For example, Go requires exported variables to start with a capital, -so the names `MyMethod` and `myMethod` will map to the same interface method. -To avoid this problem, Twirp implementations should expect and fully support -names that follow the [Protobuf Style Guide](https://developers.google.com/protocol-buffers/docs/style#services), -in particular, Service and Method names that are CamelCased (with an initial capital). - ### Requests Twirp always uses HTTP POST method to send requests, because it