grpc
/
grpc.io
mirror of https://github.com/grpc/grpc.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add "What is gRPC?" section (#250) 

* Add "What is gRPC?" section

* Move "core concepts" page to new section

* Move "What is gRPC" text to Intro page

* List techniques in Guides landing page

* Add "What is gRPC?" to Docs drop-down

* Link "Learn more" CTA to intro page

* Replace "What is gRPC?" links with "Intro" links

Replace links to
    [What is gRPC?](guides)
by
    [Introduction to gRPC](what-is-grpc/introduction)

* Replace links to "Overview" by links to Intro

Formerly the "Overview" page contained the text that is now in the intro page.

* Add redirect for concepts page

* Fix link in intro page
This commit is contained in:
Patrice Chalin 2020-05-29 20:20:03 -04:00 committed by GitHub
parent d6a7cece4b
commit 9e3c9134cf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
33 changed files with 179 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
config.yaml
View File

@ -88,6 +88,10 @@ menu:
url: /docs
weight: 1
parent: docs
- name: What is gRPC?
url: /docs/what-is-grpc
weight: 1
parent: docs
- name: Languages
url: /docs/languages
weight: 2

2
content/docs/_index.md
View File

@ -5,7 +5,7 @@ title: Overview
Welcome to the developer documentation for gRPC. Here you can learn about key
gRPC concepts, find quick starts, reference material, and tutorials for all our
[supported languages](languages), and more. If you’re new to gRPC we recommend that you read
[What is gRPC?](guides) to find out more about our system and how it works. Or
[Introduction to gRPC](what-is-grpc/introduction) to find out more about our system and how it works. Or
if you want to see gRPC in action first, visit the [Quick Start](quickstart) for
your favourite language.

111
content/docs/guides/_index.md
View File

@ -4,111 +4,8 @@ description: Task-oriented walkthroughs of common use cases
weight: 4
---
This document introduces you to gRPC and protocol buffers. gRPC can use
protocol buffers as both its Interface Definition Language (**IDL**) and as its underlying message
interchange format. If you’re new to gRPC and/or protocol buffers, read this!
If you just want to dive in and see gRPC in action first,
see our [Quick Starts](../quickstart).
The documentation covers the following techniques:
## Overview
In gRPC, a client application can directly call a method on a server application
on a different machine as if it were 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 (referred to as just a client in some
languages) that provides the same methods as the server.
![Concept Diagram](/img/landing-2.svg)
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 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
By default, gRPC uses [Protocol Buffers][], Google’s
mature open source mechanism for serializing structured data (although it
can be used with other data formats such as JSON). Here's a quick intro to how
it works. If you're already familiar with protocol buffers, feel free to skip
ahead to the next section.
The first step when working with protocol buffers is to define the structure
for the data you want to serialize in a *proto file*: this is an ordinary text
file with a `.proto` extension. Protocol buffer data is structured as
*messages*, where each message is a small logical record of information
containing a series of name-value pairs called *fields*. Here's a simple
example:
```proto
message Person {
string name = 1;
int32 id = 2;
bool has_ponycopter = 3;
}
```
Then, once you've specified your data structures, you use the protocol buffer
compiler `protoc` to generate data access classes in your preferred language(s)
from your proto definition. These provide simple accessors for each field,
like `name()` and `set_name()`, as well as methods to serialize/parse
the whole structure to/from raw bytes. So, for instance, if your chosen
language is C++, running the compiler on the example above will generate a
class called `Person`. You can then use this class in your application to
populate, serialize, and retrieve `Person` protocol buffer messages.
You define gRPC services
in ordinary proto files, with RPC method parameters and return types specified as
protocol buffer messages:
```proto
// The greeter service definition.
service Greeter {
// Sends a greeting
rpc SayHello (HelloRequest) returns (HelloReply) {}
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings
message HelloReply {
string message = 1;
}
```
gRPC uses `protoc` with a special gRPC plugin to
generate code from your proto file: you get
generated gRPC client and server code, as well as the regular protocol buffer
code for populating, serializing, and retrieving your message types. You'll
see an example of this below.
To learn more about protocol buffers, including how to install `protoc` with the
gRPC plugin in your chosen language, see the [protocol buffers documentation][protocol buffers].
## Protocol buffer versions
While [protocol buffers][] have been available to open source users for some time,
most examples from this site use protocol buffers version 3 (proto3), which has
a slightly simplified syntax, some useful new features, and supports more
languages. Proto3 is currently available in Java, C++, Dart, Python,
Objective-C, C#, a lite-runtime (Android Java), Ruby, and JavaScript from the
[protocol buffers GitHub repo][], as well as a Go language generator from the
[golang/protobuf GitHub repo][], with more languages in development. You can
find out more in the [proto3 language guide][] and the [reference
documentation][] available for each language. The reference documentation also
includes a [formal specification][] for the `.proto` file format.
In general, while you can use proto2 (the current default protocol buffers
version), 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.
[formal specification]: https://developers.google.com/protocol-buffers/docs/reference/proto3-spec
[golang/protobuf GitHub repo]: https://github.com/golang/protobuf
[proto3 language guide]: https://developers.google.com/protocol-buffers/docs/proto3
[protocol buffers GitHub repo]: https://github.com/google/protobuf/releases
[protocol buffers]: https://developers.google.com/protocol-buffers/docs/overview
[reference documentation]: https://developers.google.com/protocol-buffers/docs/reference/overview
- [Authentication](auth)
- [Benchmarking](benchmarking)
- [Error handling](error)

2
content/docs/languages/_index.md
View File

@ -1,7 +1,7 @@
---
title: Supported languages and platforms
short: Languages
weight: 1
weight: 2
nav_children: section
---

4
content/docs/languages/android/basics.md
View File

@ -11,7 +11,7 @@ By walking through this example you'll learn how to:
- Generate client code using the protocol buffer compiler.
- Use the Java gRPC API to write a simple mobile client for your service.
It assumes that you have read the [Overview](/docs/) and are familiar with [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
It assumes that you have read the [Introduction to gRPC](/docs/what-is-grpc/introduction) and are familiar with [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
This guide also does not cover anything on the server side. You can check the [Java guide](/docs/tutorials/basic/java/) for more information.
### Why use gRPC?
@ -40,7 +40,7 @@ interface code - if you don't already, follow the setup instructions in the
### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to define the gRPC *service* and the method *request* and *response* types using [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). You can see the complete .proto file in [routeguide/app/src/main/proto/route_guide.proto](https://github.com/grpc/grpc-java/blob/{{< param grpc_java_release_tag >}}/examples/android/routeguide/app/src/main/proto/route_guide.proto).
Our first step (as you'll know from the [Introduction to gRPC](/docs/what-is-grpc/introduction)) is to define the gRPC *service* and the method *request* and *response* types using [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). You can see the complete .proto file in [routeguide/app/src/main/proto/route_guide.proto](https://github.com/grpc/grpc-java/blob/{{< param grpc_java_release_tag >}}/examples/android/routeguide/app/src/main/proto/route_guide.proto).
As we're generating Java code in this example, we've specified a `java_package` file option in our .proto:

2
content/docs/languages/android/quickstart.md
View File

@ -193,7 +193,7 @@ enter `10.0.2.2` and `50051` as the `Host` and `Port`.
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Android Java](/docs/tutorials/basic/android/).
- Explore the gRPC Java core API in its [reference

8
content/docs/languages/cpp/async.md
View File

@ -5,16 +5,16 @@ title: Asynchronous-API Tutorial
This tutorial shows you how to write a simple server and client in C++ using
gRPC's asynchronous/non-blocking APIs. It assumes you are already familiar with
writing simple synchronous gRPC code, as described in [gRPC Basics:
C++](/docs/tutorials/basic/cpp/). The example used in this tutorial follows on
from the basic [Greeter example](https://github.com/grpc/grpc/tree/{{< param grpc_release_tag >}}/examples/cpp/helloworld) we used in the
[overview](/docs/). You'll find it along with installation
C++](/docs/tutorials/basic/cpp/). The example used in this tutorial follows
from the basic [Greeter example](https://github.com/grpc/grpc/tree/{{< param grpc_release_tag >}}/examples/cpp/helloworld) used in the
[quick start](../quickstart). You'll find it along with installation
instructions in
[grpc/examples/cpp/helloworld](https://github.com/grpc/grpc/tree/{{< param grpc_release_tag >}}/examples/cpp/helloworld).
### Overview
gRPC uses the
[`CompletionQueue`](/grpc/cpp/classgrpc__impl_1_1_completion_queue.html)
[CompletionQueue](/grpc/cpp/classgrpc__impl_1_1_completion_queue.html)
API for asynchronous operations. The basic work flow
is as follows:

4
content/docs/languages/cpp/basics.md
View File

@ -12,7 +12,7 @@ By walking through this example you'll learn how to:
- Generate server and client code using the protocol buffer compiler.
- Use the C++ gRPC API to write a simple client and server for your service.
It assumes that you have read the [Overview](/docs/) and are familiar
It assumes that you have read the [Introduction to gRPC](/docs/what-is-grpc/introduction) and are familiar
with [protocol
buffers](https://developers.google.com/protocol-buffers/docs/overview). Note
that the example in this tutorial uses the proto3 version of the protocol
@ -61,7 +61,7 @@ client interface code - if you don't already, follow the setup instructions in
### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to
Our first step (as you'll know from the [Introduction to gRPC](/docs/what-is-grpc/introduction)) is to
define the gRPC *service* and the method *request* and *response* types using
[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
You can see the complete .proto file in

4
content/docs/languages/cpp/quickstart.md
View File

@ -172,7 +172,7 @@ Congratulations! You've just run a client-server application with gRPC.
Now let's look at how to update the application with an extra method on the
server for the client to call. Our gRPC service is defined using protocol
buffers; you can find out lots more about how to define a service in a `.proto`
file in [What is gRPC?](/docs/guides) and [gRPC Basics:
file in [Introduction to gRPC](/docs/what-is-grpc/introduction) and [gRPC Basics:
C++](/docs/tutorials/basic/cpp). For now all you need to know is that both the
server and the client stub have a `SayHello()` RPC method that takes a
`HelloRequest` parameter from the client and returns a `HelloResponse` from the
@ -351,7 +351,7 @@ from the example **build** directory `examples/cpp/helloworld/cmake/build`:
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts).
- Work through a more detailed tutorial in [gRPC Basics: C++](/docs/tutorials/basic/cpp).
- Explore the gRPC C++ core API in its [reference

4
content/docs/languages/csharp/basics.md
View File

@ -11,7 +11,7 @@ By walking through this example you'll learn how to:
- Generate server and client code using the protocol buffer compiler.
- Use the C# gRPC API to write a simple client and server for your service.
It assumes that you have read the [Overview](/docs/) and are familiar
It assumes that you have read the [Introduction to gRPC](/docs/what-is-grpc/introduction) and are familiar
with [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). Note that the
example in this tutorial uses the proto3 version of the protocol buffers
language: you can find out more in the
@ -53,7 +53,7 @@ instructions](https://github.com/grpc/grpc/tree/{{< param grpc_release_tag >}}/s
### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to
Our first step (as you'll know from the [Introduction to gRPC](/docs/what-is-grpc/introduction)) is to
define the gRPC *service* and the method *request* and *response* types using
[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
You can see the complete .proto file in

2
content/docs/languages/csharp/quickstart.md
View File

@ -239,7 +239,7 @@ Just like we did before, from the `examples/csharp/Helloworld` directory:
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: C#](/docs/tutorials/basic/csharp/).
- Explore the gRPC C# core API in its [reference

4
content/docs/languages/dart/basics.md
View File

@ -12,7 +12,7 @@ By walking through this example you'll learn how to:
- Generate server and client code using the protocol buffer compiler.
- Use the Dart gRPC API to write a simple client and server for your service.
It assumes that you have read the [Overview](/docs/) and are familiar
It assumes that you have read the [Introduction to gRPC](/docs/what-is-grpc/introduction) and are familiar
with [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). Note that the
example in this tutorial uses the proto3 version of the protocol buffers
language: you can find out more in the
@ -55,7 +55,7 @@ You also should have the relevant tools installed to generate the server and cli
### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to
Our first step (as you'll know from the [Introduction to gRPC](/docs/what-is-grpc/introduction)) is to
define the gRPC *service* and the method *request* and *response* types using
[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). You can see the
complete .proto file in

2
content/docs/languages/dart/quickstart.md
View File

@ -232,7 +232,7 @@ from the `example/helloworld` directory:
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Dart](/docs/tutorials/basic/dart/).
- Explore the [Dart gRPC API reference][].

4
content/docs/languages/go/basics.md
View File

@ -12,7 +12,7 @@ By walking through this example you'll learn how to:
- Generate server and client code using the protocol buffer compiler.
- Use the Go gRPC API to write a simple client and server for your service.
It assumes that you have read the [Overview](/docs/) and are familiar with
It assumes that you have read the [Introduction to gRPC](/docs/what-is-grpc/introduction) and are familiar with
[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
Note that the example in this tutorial uses the proto3 version of the protocol
buffers language: you can find out more in the [proto3 language
@ -58,7 +58,7 @@ client interface code - if you don't already, follow the setup instructions in
### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to
Our first step (as you'll know from the [Introduction to gRPC](/docs/what-is-grpc/introduction)) is to
define the gRPC *service* and the method *request* and *response* types using
[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
You can see the complete .proto file in

2
content/docs/languages/go/quickstart.md
View File

@ -195,7 +195,7 @@ from the `examples/helloworld` directory:
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Go](/docs/tutorials/basic/go/).
- Explore the gRPC Go core API in its [reference

4
content/docs/languages/java/basics.md
View File

@ -12,7 +12,7 @@ By walking through this example you'll learn how to:
- Generate server and client code using the protocol buffer compiler.
- Use the Java gRPC API to write a simple client and server for your service.
It assumes that you have read the [Overview](/docs/) and are familiar
It assumes that you have read the [Introduction to gRPC](/docs/what-is-grpc/introduction) and are familiar
with [protocol
buffers](https://developers.google.com/protocol-buffers/docs/overview). Note
that the example in this tutorial uses the
@ -56,7 +56,7 @@ $ cd grpc-java/examples/routeguide
### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to
Our first step (as you'll know from the [Introduction to gRPC](/docs/what-is-grpc/introduction)) is to
define the gRPC *service* and the method *request* and *response* types using
[protocol
buffers](https://developers.google.com/protocol-buffers/docs/overview). You can

2
content/docs/languages/java/quickstart.md
View File

@ -187,7 +187,7 @@ Just like we did before, from the `examples` directory:
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Java](/docs/tutorials/basic/java/).
- Explore the gRPC Java core API in its [reference

4
content/docs/languages/kotlin/basics.md
View File

@ -12,7 +12,7 @@ By walking through this example you'll learn how to:
- Generate server and client code using the protocol buffer compiler.
- Use the Kotlin gRPC API to write a simple client and server for your service.
It assumes that you have read the [Overview](/docs) and are familiar
It assumes that you have read the [Introduction to gRPC](/docs/what-is-grpc/introduction) and are familiar
with [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). Note that the
example in this tutorial uses the proto3 version of the protocol buffers
language: you can find out more in the
@ -53,7 +53,7 @@ $ cd grpc-kotlin/examples/src/main/kotlin/io/grpc/examples/routeguide
### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to
Our first step (as you'll know from the [Introduction to gRPC](/docs/what-is-grpc/introduction)) is to
define the gRPC *service* and the method *request* and *response* types using
[protocol
buffers](https://developers.google.com/protocol-buffers/docs/overview). You can

2
content/docs/languages/kotlin/quickstart.md
View File

@ -191,7 +191,7 @@ from the `examples` directory:
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Kotlin](/docs/tutorials/basic/kotlin/).
- Explore the gRPC Kotlin core API in its [reference

4
content/docs/languages/node/basics.md
View File

@ -11,7 +11,7 @@ By walking through this example you'll learn how to:
- Define a service in a .proto file.
- Use the Node.js gRPC API to write a simple client and server for your service.
It assumes that you have read the [Overview](/docs/) and are familiar
It assumes that you have read the [Introduction to gRPC](/docs/what-is-grpc/introduction) and are familiar
with [protocol
buffers](https://developers.google.com/protocol-buffers/docs/overview). Note
that the example in this tutorial uses the
@ -71,7 +71,7 @@ client interface code - if you don't already, follow the setup instructions in
### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to
Our first step (as you'll know from the [Introduction to gRPC](/docs/what-is-grpc/introduction)) is to
define the gRPC *service* and the method *request* and *response* types using
[protocol
buffers](https://developers.google.com/protocol-buffers/docs/overview). You can

2
content/docs/languages/node/quickstart.md
View File

@ -161,7 +161,7 @@ Just like we did before, from the `examples/node/dynamic_codegen` directory:
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Node](/docs/tutorials/basic/node/).
- Explore the gRPC Node core API in its [reference

2
content/docs/languages/objective-c/oauth2.md
View File

@ -16,7 +16,7 @@ By walking through it you'll also learn how to use the Objective-C gRPC API to:
It assumes you know the basics on how to make gRPC API calls using the
Objective-C client library, as shown in [gRPC Basics:
Objective-C](/docs/tutorials/basic/objective-c/) and the
[overview](/docs/), and are familiar with OAuth2 concepts like _access
[Introduction to gRPC](/docs/what-is-grpc/introduction), and are familiar with OAuth2 concepts like _access
token_.
### Example code and setup {#setup}

2
content/docs/languages/objective-c/quickstart.md
View File

@ -311,7 +311,7 @@ Cannot find `protoc` when building HelloWorld
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Objective-C](/docs/tutorials/basic/objective-c/).
- Explore the Objective-C core API in its [reference

2
content/docs/languages/php/quickstart.md
View File

@ -435,7 +435,7 @@ Just like we did before, from the `examples/node/dynamic_codegen` directory:
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: PHP](/docs/tutorials/basic/php/).
- Explore the gRPC PHP core API in its [reference

4
content/docs/languages/python/basics.md
View File

@ -12,7 +12,7 @@ By walking through this example you'll learn how to:
- Generate server and client code using the protocol buffer compiler.
- Use the Python gRPC API to write a simple client and server for your service.
It assumes that you have read the [Overview](/docs/guides/#overview) and are familiar
It assumes that you have read the [Introduction to gRPC](/docs/what-is-grpc/introduction) and are familiar
with [protocol
buffers](https://developers.google.com/protocol-buffers/docs/overview). You can
find out more in the [proto3 language
@ -58,7 +58,7 @@ client interface code - if you don't already, follow the setup instructions in
### Defining the service
Your first step (as you'll know from the [Overview](/docs/guides/#overview)) is to
Your first step (as you'll know from the [Introduction to gRPC](/docs/what-is-grpc/introduction)) is to
define the gRPC *service* and the method *request* and *response* types using
[protocol
buffers](https://developers.google.com/protocol-buffers/docs/overview). You can

4
content/docs/languages/python/quickstart.md
View File

@ -104,7 +104,7 @@ Congratulations! You've just run a client-server application with gRPC.
Now let's look at how to update the application with an extra method on the
server for the client to call. Our gRPC service is defined using protocol
buffers; you can find out lots more about how to define a service in a `.proto`
file in [What is gRPC?](/docs/guides/) and [gRPC Basics: Python](/docs/tutorials/basic/python/). For now all you need
file in [Introduction to gRPC](/docs/what-is-grpc/introduction) and [gRPC Basics: Python](/docs/tutorials/basic/python/). For now all you need
to know is that both the server and the client "stub" have a `SayHello` RPC
method that takes a `HelloRequest` parameter from the client and returns a
`HelloReply` from the server, and that this method is defined like this:
@ -222,7 +222,7 @@ Just like we did before, from the `examples/python/helloworld` directory:
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Python](/docs/tutorials/basic/python/).
- Explore the gRPC Python core API in its [reference

4
content/docs/languages/ruby/basics.md
View File

@ -11,7 +11,7 @@ By walking through this example you'll learn how to:
- Generate server and client code using the protocol buffer compiler.
- Use the Ruby gRPC API to write a simple client and server for your service.
It assumes that you have read the [Overview](/docs/) and are familiar
It assumes that you have read the [Introduction to gRPC](/docs/what-is-grpc/introduction) and are familiar
with [protocol
buffers](https://developers.google.com/protocol-buffers/docs/overview). Note
that the example in this tutorial uses the proto3 version of the protocol
@ -58,7 +58,7 @@ client interface code - if you don't already, follow the setup instructions in
### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to
Our first step (as you'll know from the [Introduction to gRPC](/docs/what-is-grpc/introduction)) is to
define the gRPC *service* and the method *request* and *response* types using
[protocol
buffers](https://developers.google.com/protocol-buffers/docs/overview). You can

2
content/docs/languages/ruby/quickstart.md
View File

@ -181,7 +181,7 @@ Just like we did before, from the `examples/ruby` directory:
### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
- Read a full explanation of how gRPC works in [Introduction to gRPC](/docs/what-is-grpc/introduction)
and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Ruby](/docs/tutorials/basic/ruby/).
- Explore the gRPC Ruby core API in its [reference

9
content/docs/what-is-grpc/_index.md Normal file
View File

@ -0,0 +1,9 @@
---
title: What is gRPC?
weight: 1
---
New to gRPC? Start with the following pages:
- [Introduction to gRPC](introduction)
- [Core concepts, architecture and lifecycle](core-concepts)

7
content/docs/guides/concepts.md → content/docs/what-is-grpc/core-concepts.md
View File

@ -1,11 +1,12 @@
---
title: gRPC Concepts
description: |-
title: Core concepts, architecture and lifecycle
short: Core concepts
description: >-
An introduction to key gRPC concepts, with an overview of gRPC architecture
and RPC life cycle.
---
Not familiar with gRPC? First read [What is gRPC?](/docs/guides). For
Not familiar with gRPC? First read [Introduction to gRPC](../introduction). For
language-specific details, see the Quick Start, tutorial, and reference
documentation for your language of choice.

115
content/docs/what-is-grpc/introduction.md Normal file
View File

@ -0,0 +1,115 @@
---
title: Introduction to gRPC
short: Introduction
description: An introduction to gRPC and protocol buffers.
weight: 10
---
This page introduces you to gRPC and protocol buffers. gRPC can use
protocol buffers as both its Interface Definition Language (**IDL**) and as its underlying message
interchange format. If you’re new to gRPC and/or protocol buffers, read this!
If you just want to dive in and see gRPC in action first,
see our [Quick Starts](/docs/quickstart).
## Overview
In gRPC, a client application can directly call a method on a server application
on a different machine as if it were 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 (referred to as just a client in some
languages) that provides the same methods as the server.
![Concept Diagram](/img/landing-2.svg)
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 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
By default, gRPC uses [Protocol Buffers][], Google’s
mature open source mechanism for serializing structured data (although it
can be used with other data formats such as JSON). Here's a quick intro to how
it works. If you're already familiar with protocol buffers, feel free to skip
ahead to the next section.
The first step when working with protocol buffers is to define the structure
for the data you want to serialize in a *proto file*: this is an ordinary text
file with a `.proto` extension. Protocol buffer data is structured as
*messages*, where each message is a small logical record of information
containing a series of name-value pairs called *fields*. Here's a simple
example:
```proto
message Person {
string name = 1;
int32 id = 2;
bool has_ponycopter = 3;
}
```
Then, once you've specified your data structures, you use the protocol buffer
compiler `protoc` to generate data access classes in your preferred language(s)
from your proto definition. These provide simple accessors for each field,
like `name()` and `set_name()`, as well as methods to serialize/parse
the whole structure to/from raw bytes. So, for instance, if your chosen
language is C++, running the compiler on the example above will generate a
class called `Person`. You can then use this class in your application to
populate, serialize, and retrieve `Person` protocol buffer messages.
You define gRPC services
in ordinary proto files, with RPC method parameters and return types specified as
protocol buffer messages:
```proto
// The greeter service definition.
service Greeter {
// Sends a greeting
rpc SayHello (HelloRequest) returns (HelloReply) {}
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings
message HelloReply {
string message = 1;
}
```
gRPC uses `protoc` with a special gRPC plugin to
generate code from your proto file: you get
generated gRPC client and server code, as well as the regular protocol buffer
code for populating, serializing, and retrieving your message types. You'll
see an example of this below.
To learn more about protocol buffers, including how to install `protoc` with the
gRPC plugin in your chosen language, see the [protocol buffers documentation][protocol buffers].
## Protocol buffer versions
While [protocol buffers][] have been available to open source users for some time,
most examples from this site use protocol buffers version 3 (proto3), which has
a slightly simplified syntax, some useful new features, and supports more
languages. Proto3 is currently available in Java, C++, Dart, Python,
Objective-C, C#, a lite-runtime (Android Java), Ruby, and JavaScript from the
[protocol buffers GitHub repo][], as well as a Go language generator from the
[golang/protobuf GitHub repo][], with more languages in development. You can
find out more in the [proto3 language guide][] and the [reference
documentation][] available for each language. The reference documentation also
includes a [formal specification][] for the `.proto` file format.
In general, while you can use proto2 (the current default protocol buffers
version), 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.
[formal specification]: https://developers.google.com/protocol-buffers/docs/reference/proto3-spec
[golang/protobuf GitHub repo]: https://github.com/golang/protobuf
[proto3 language guide]: https://developers.google.com/protocol-buffers/docs/proto3
[protocol buffers GitHub repo]: https://github.com/google/protobuf/releases
[protocol buffers]: https://developers.google.com/protocol-buffers/docs/overview
[reference documentation]: https://developers.google.com/protocol-buffers/docs/reference/overview

1
layouts/index.redirects
View File

@ -1,3 +1,4 @@
/docs/guides/concepts /docs/what-is-grpc/core-concepts
/docs/guides/contributing /community
/docs/languages/csharp/quickstart-dotnet /docs/languages/csharp/dotnet
/docs/quickstart/csharp-dotnet /docs/languages/csharp/dotnet

2
layouts/partials/home/hero.html
View File

@ -10,7 +10,7 @@
<br />
<div class="buttons are-medium is-centered">
<a class="button is-primary has-text-weight-bold" href="/docs/guides">
<a class="button is-primary has-text-weight-bold" href="/docs/what-is-grpc/introduction">
Learn more
</a>
<a class="button is-primary has-text-weight-bold" href="/docs/quickstart">