From 461780145938e452e113f4eb951c3a28ff69b214 Mon Sep 17 00:00:00 2001 From: Lisa Carey Date: Fri, 13 Feb 2015 16:38:49 +0000 Subject: [PATCH 1/6] Starting intro --- README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/README.md b/README.md index e3719357ea5..592e1663f73 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,33 @@ Hello World example. More documentation is coming soon! ## What is gRPC? +gRPC is It enables communication between clients and servers using any combination of gRPC's supported languages, helping you to build distributed applications and services. + +In gRPC, like + +### Plays well with Protocol Buffers + +While gRPC’s architecture allows it to be extended for use with other +data formats such as JSON, by default it uses protocol buffers, Google’s +mature open source mechanism for serializing structured data. As you'll +see in our example below, you define gRPC interfaces using proto files and +protocol buffer messages, letting you take advantage of protocol buffers’ +efficient serialization, simple IDL, and easy interface updating. You +can find out lots more about protocol buffers in the [Protocol Buffers +documentation](https://developers.google.com/protocol-buffers/docs/overview). + +Note that our examples use a new flavour of protocol buffers called proto3, +which has a slightly simplified syntax, some useful new features, and supports +lots more languages. This is currently available as an alpha release in +[languages] from [wherever it's going], with more languages in development. In +general, we recommend that you use proto3 with gRPC as it lets you use the +full range of gRPC-supported languages, as well as avoiding any compatibility +issues with proto2 clients talking to proto3 servers and vice versa. + +If you need to continue using proto2 for Java, C++, or Python but want +to try gRPC, you can see an example using a proto2 gRPC client and server +[wherever we put it]. + ## TODO: basic conceptual intro (anything more in-depth will go in gRPC Concepts doc) From bdcda72cec23554d5ef1dd5695de9e97e8bb3235 Mon Sep 17 00:00:00 2001 From: Lisa Carey Date: Fri, 13 Feb 2015 16:40:23 +0000 Subject: [PATCH 2/6] Fixed typo --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 592e1663f73..413f5008a2f 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,9 @@ Hello World example. More documentation is coming soon! ## What is gRPC? -gRPC is It enables communication between clients and servers using any combination of gRPC's supported languages, helping you to build distributed applications and services. +gRPC enables communication between clients and servers using any combination of gRPC's supported languages, helping you to build distributed applications and services. -In gRPC, like +In gRPC, like other RPC systems... ### Plays well with Protocol Buffers @@ -46,7 +46,7 @@ Now that you know a bit more about gRPC, the easiest way to see how it works is to look at a simple example. Our Hello World walks you through the construction of a simple gRPC client-server application, showing you how to: -- Create a protobuf schema that defines a simple RPC service with a single +- Create a protocol buffers schema that defines a simple RPC service with a single Hello World method. - Create a Java server that implements the schema interface. - Create a Java client that accesses the Java server. From 907119eafd930085c8067e7bdaabbe294cef9605 Mon Sep 17 00:00:00 2001 From: Lisa Carey Date: Fri, 13 Feb 2015 16:52:03 +0000 Subject: [PATCH 3/6] Intro tweaks --- README.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 413f5008a2f..2d3a3a8f5b5 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,7 @@ Hello World example. More documentation is coming soon! ## What is gRPC? -gRPC enables communication between clients and servers using any combination of gRPC's supported languages, helping you to build distributed applications and services. - -In gRPC, like other RPC systems... +In gRPC, like other RPC systems, a *client* application can directly call methods on a *server* application on a different machine as if it was a local object, making it easier for you to create distributed applications and services. gRPC clients and servers can run and talk to each other in a variety of environments - from servers inside Google to your own desktop - and can be written in any of gRPC's supported languages. So, for example, you can easily create a gRPC server in Java with clients in Go, Python, or Ruby. ### Plays well with Protocol Buffers @@ -68,9 +66,8 @@ languages are coming soon. ### Setup -The rest of this page explains how to set up your local machine to work with -the example code. -If you just want to read the example, you can go straight to the [next step](#servicedef). +This section explains how to set up your local machine to work with +the example code. If you just want to read the example, you can go straight to the [next step](#servicedef). #### Install Git From e82f310a440c75e5234c4aa6b0028ec5b550d8df Mon Sep 17 00:00:00 2001 From: Lisa Carey Date: Tue, 17 Feb 2015 16:27:51 +0000 Subject: [PATCH 4/6] Added a simple overview/protocol buffers information --- README.md | 45 ++++++++++++++++++++++----------------------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 2d3a3a8f5b5..a1575392e02 100644 --- a/README.md +++ b/README.md @@ -10,32 +10,34 @@ Hello World example. More documentation is coming soon! ## What is gRPC? -In gRPC, like other RPC systems, a *client* application can directly call methods on a *server* application on a different machine as if it was a local object, making it easier for you to create distributed applications and services. gRPC clients and servers can run and talk to each other in a variety of environments - from servers inside Google to your own desktop - and can be written in any of gRPC's supported languages. So, for example, you can easily create a gRPC server in Java with clients in Go, Python, or Ruby. +In gRPC, like other RPC systems, a *client* application can directly call methods on a *server* application on a different machine as if it was a local object, making it easier for you to create distributed applications and services. As in many RPC systems, gRPC is based around the idea of defining a *service*, specifying the methods that can be called remotely with their parameters and return types. On the server side, the server implements this interface and runs a gRPC server to handle client calls. On the client side, the client has a *stub* that provides exactly the same methods as the server. -### Plays well with Protocol Buffers +##TODO: diagram? + +gRPC clients and servers can run and talk to each other in a variety of environments - from servers inside Google to your own desktop - and can be written in any of gRPC's [supported languages](link to list). So, for example, you can easily create a gRPC server in Java with clients in Go, Python, or Ruby. In addition, the latest Google APIs will have gRPC versions of their interfaces, letting you easily build Google functionality into your applications. + + +### Working with protocol buffers While gRPC’s architecture allows it to be extended for use with other -data formats such as JSON, by default it uses protocol buffers, Google’s +data formats such as JSON, by default it uses *protocol buffers*, Google’s mature open source mechanism for serializing structured data. As you'll -see in our example below, you define gRPC interfaces using proto files and -protocol buffer messages, letting you take advantage of protocol buffers’ -efficient serialization, simple IDL, and easy interface updating. You -can find out lots more about protocol buffers in the [Protocol Buffers -documentation](https://developers.google.com/protocol-buffers/docs/overview). +see in our example below, you define gRPC services using *proto files*, with method parameters and return types specified as protocol buffer message types. You +can find out lots more about protocol buffers in the [Protocol Buffers documentation](https://developers.google.com/protocol-buffers/docs/overview). + +#### Protocol buffer versions -Note that our examples use a new flavour of protocol buffers called proto3, +While protocol buffers have been available for open source users for some time, our examples use a new flavour of protocol buffers called proto3, which has a slightly simplified syntax, some useful new features, and supports lots more languages. This is currently available as an alpha release in -[languages] from [wherever it's going], with more languages in development. In -general, we recommend that you use proto3 with gRPC as it lets you use the -full range of gRPC-supported languages, as well as avoiding any compatibility -issues with proto2 clients talking to proto3 servers and vice versa. +[languages] from [wherever it's going], with more languages in development. -If you need to continue using proto2 for Java, C++, or Python but want +In general, we recommend that you use proto3 with gRPC as it lets you use the +full range of gRPC-supported languages, as well as avoiding compatibility +issues with proto2 clients talking to proto3 servers and vice versa. You can find out more about these potential issues in [where should we put this info? It's important but not really part of an overview]. If you need to continue using proto2 for Java, C++, or Python but want to try gRPC, you can see an example using a proto2 gRPC client and server [wherever we put it]. -## TODO: basic conceptual intro (anything more in-depth will go in gRPC Concepts doc) ## Hello gRPC! @@ -46,9 +48,9 @@ construction of a simple gRPC client-server application, showing you how to: - Create a protocol buffers schema that defines a simple RPC service with a single Hello World method. -- Create a Java server that implements the schema interface. +- Create a Java server that implements thid interface. - Create a Java client that accesses the Java server. -- Create a Go client that accesses the same Java server. +- Create a [probably need a different language now] client that accesses the same Java server. - Update the service with more advanced features like RPC streaming. The complete code for the example is available in the `grpc-common` GitHub repository. You can @@ -134,12 +136,9 @@ with generating the code yourself, download and install protoc from its The first step in creating our example is to define a *service*: an RPC service specifies the methods that can be called remotely with their parameters -and return types. In gRPC, we use the protocol buffers interface definition -language (IDL) to define our service methods, and the parameters and return -types are defined as protocol buffer message types. Both the client and the -server use interface code generated from the service definition. If you're not -familiar with protocol buffers, you can find out more in the [Protocol Buffers -Developer Guide](https://developers.google.com/protocol-buffers/docs/overview). +and return types. As you saw in the [overview](#protocolbuffers) above, gRPC does this using [protocol buffers]((https://developers.google.com/protocol-buffers/docs/overview). We use the protocol buffers interface definition language (IDL) to define our service methods, and define the parameters and return +types as protocol buffer message types. Both the client and the +server use interface code generated from the service definition. Here's our example service definition, defined using protocol buffers IDL in [helloworld.proto](java/src/main/proto/helloworld.proto). The `Greeting` service From e416242fe1fcf43c95496c10da28a0131d102457 Mon Sep 17 00:00:00 2001 From: Lisa Carey Date: Tue, 17 Feb 2015 16:30:13 +0000 Subject: [PATCH 5/6] Tidy formatting --- README.md | 46 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 36 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index a1575392e02..1820becdf06 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,24 @@ Hello World example. More documentation is coming soon! ## What is gRPC? -In gRPC, like other RPC systems, a *client* application can directly call methods on a *server* application on a different machine as if it was a local object, making it easier for you to create distributed applications and services. As in many RPC systems, gRPC is based around the idea of defining a *service*, specifying the methods that can be called remotely with their parameters and return types. On the server side, the server implements this interface and runs a gRPC server to handle client calls. On the client side, the client has a *stub* that provides exactly the same methods as the server. +In gRPC, like other RPC systems, a *client* application can directly call +methods on a *server* application on a different machine as if it was a +local object, making it easier for you to create distributed applications and +services. As in many RPC systems, gRPC is based around the idea of defining +a *service*, specifying the methods that can be called remotely with their +parameters and return types. On the server side, the server implements this +interface and runs a gRPC server to handle client calls. On the client side, +the client has a *stub* that provides exactly the same methods as the server. ##TODO: diagram? -gRPC clients and servers can run and talk to each other in a variety of environments - from servers inside Google to your own desktop - and can be written in any of gRPC's [supported languages](link to list). So, for example, you can easily create a gRPC server in Java with clients in Go, Python, or Ruby. In addition, the latest Google APIs will have gRPC versions of their interfaces, letting you easily build Google functionality into your applications. +gRPC clients and servers can run and talk to each other in a variety of +environments - from servers inside Google to your own desktop - and can +be written in any of gRPC's [supported languages](link to list). So, for +example, you can easily create a gRPC server in Java with clients in Go, +Python, or Ruby. In addition, the latest Google APIs will have gRPC versions +of their interfaces, letting you easily build Google functionality into +your applications. ### Working with protocol buffers @@ -22,19 +35,26 @@ gRPC clients and servers can run and talk to each other in a variety of environm While gRPC’s architecture allows it to be extended for use with other data formats such as JSON, by default it uses *protocol buffers*, Google’s mature open source mechanism for serializing structured data. As you'll -see in our example below, you define gRPC services using *proto files*, with method parameters and return types specified as protocol buffer message types. You -can find out lots more about protocol buffers in the [Protocol Buffers documentation](https://developers.google.com/protocol-buffers/docs/overview). +see in our example below, you define gRPC services using *proto files*, +with method parameters and return types specified as protocol buffer message +types. You +can find out lots more about protocol buffers in the [Protocol Buffers +documentation](https://developers.google.com/protocol-buffers/docs/overview). #### Protocol buffer versions -While protocol buffers have been available for open source users for some time, our examples use a new flavour of protocol buffers called proto3, +While protocol buffers have been available for open source users for some +time, our examples use a new flavour of protocol buffers called proto3, which has a slightly simplified syntax, some useful new features, and supports lots more languages. This is currently available as an alpha release in [languages] from [wherever it's going], with more languages in development. In general, we recommend that you use proto3 with gRPC as it lets you use the full range of gRPC-supported languages, as well as avoiding compatibility -issues with proto2 clients talking to proto3 servers and vice versa. You can find out more about these potential issues in [where should we put this info? It's important but not really part of an overview]. If you need to continue using proto2 for Java, C++, or Python but want +issues with proto2 clients talking to proto3 servers and vice versa. You +can find out more about these potential issues in [where should we put this +info? It's important but not really part of an overview]. If you need to +continue using proto2 for Java, C++, or Python but want to try gRPC, you can see an example using a proto2 gRPC client and server [wherever we put it]. @@ -83,9 +103,11 @@ the code to hack on #### Get the source code -The example code for this and our other examples lives in the `grpc-common` GitHub repository. Clone this repository to your local machine by running the +The example code for this and our other examples lives in the `grpc-common` +GitHub repository. Clone this repository to your local machine by running the following command: + ``` git clone https://github.com/google/grpc-common.git ``` @@ -136,13 +158,17 @@ with generating the code yourself, download and install protoc from its The first step in creating our example is to define a *service*: an RPC service specifies the methods that can be called remotely with their parameters -and return types. As you saw in the [overview](#protocolbuffers) above, gRPC does this using [protocol buffers]((https://developers.google.com/protocol-buffers/docs/overview). We use the protocol buffers interface definition language (IDL) to define our service methods, and define the parameters and return +and return types. As you saw in the +[overview](#protocolbuffers) above, gRPC does this using [protocol +buffers]((https://developers.google.com/protocol-buffers/docs/overview). We +use the protocol buffers interface definition language (IDL) to define our +service methods, and define the parameters and return types as protocol buffer message types. Both the client and the server use interface code generated from the service definition. Here's our example service definition, defined using protocol buffers IDL in -[helloworld.proto](java/src/main/proto/helloworld.proto). The `Greeting` service -has one method, `hello`, that lets the server receive a single `HelloRequest` +[helloworld.proto](java/src/main/proto/helloworld.proto). The `Greeting` +service has one method, `hello`, that lets the server receive a single `HelloRequest` message from the remote client containing the user's name, then send back a greeting in a single `HelloReply`. This is the simplest type of RPC you can specify in gRPC - we'll look at some other types later in this document. From b789acd2d2ce0d94064527c2890db4887140616f Mon Sep 17 00:00:00 2001 From: Lisa Carey Date: Tue, 17 Feb 2015 16:41:45 +0000 Subject: [PATCH 6/6] Fixed typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1820becdf06..fdbd1f0de02 100644 --- a/README.md +++ b/README.md @@ -160,7 +160,7 @@ The first step in creating our example is to define a *service*: an RPC service specifies the methods that can be called remotely with their parameters and return types. As you saw in the [overview](#protocolbuffers) above, gRPC does this using [protocol -buffers]((https://developers.google.com/protocol-buffers/docs/overview). We +buffers](https://developers.google.com/protocol-buffers/docs/overview). We use the protocol buffers interface definition language (IDL) to define our service methods, and define the parameters and return types as protocol buffer message types. Both the client and the