Synchronize new proto changes.

google/api/http.proto

@@ -1,4 +1,4 @@
-// Copyright 2016 Google Inc.
+// Copyright 2018 Google Inc.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -24,7 +24,7 @@ option java_package = "com.google.api";
 option objc_class_prefix = "GAPI";
 
 
-// Defines the HTTP configuration for a service. It contains a list of
+// Defines the HTTP configuration for an API service. It contains a list of
 // [HttpRule][google.api.HttpRule], each specifying the mapping of an RPC method
 // to one or more HTTP REST API methods.
 message Http {
@@ -32,14 +32,22 @@ message Http {
   //
   // **NOTE:** All service configuration rules follow "last one wins" order.
   repeated HttpRule rules = 1;
+
+  // When set to true, URL path parmeters will be fully URI-decoded except in
+  // cases of single segment matches in reserved expansion, where "%2F" will be
+  // left encoded.
+  //
+  // The default behavior is to not decode RFC 6570 reserved characters in multi
+  // segment matches.
+  bool fully_decode_reserved_expansion = 2;
 }
 
 // `HttpRule` defines the mapping of an RPC method to one or more HTTP
-// REST APIs.  The mapping determines what portions of the request
-// message are populated from the path, query parameters, or body of
-// the HTTP request.  The mapping is typically specified as an
-// `google.api.http` annotation, see "google/api/annotations.proto"
-// for details.
+// REST API methods. The mapping specifies how different portions of the RPC
+// request message are mapped to URL path, URL query parameters, and
+// HTTP request body. The mapping is typically specified as an
+// `google.api.http` annotation on the RPC method,
+// see "google/api/annotations.proto" for details.
 //
 // The mapping consists of a field specifying the path template and
 // method kind.  The path template can refer to fields in the request
@@ -87,6 +95,11 @@ message Http {
 // parameters. Assume the following definition of the request message:
 //
 //
+//     service Messaging {
+//       rpc GetMessage(GetMessageRequest) returns (Message) {
+//         option (google.api.http).get = "/v1/messages/{message_id}";
+//       }
+//     }
 //     message GetMessageRequest {
 //       message SubMessage {
 //         string subfield = 1;
@@ -199,7 +212,7 @@ message Http {
 // to the request message are as follows:
 //
 // 1. The `body` field specifies either `*` or a field path, or is
-//    omitted. If omitted, it assumes there is no HTTP body.
+//    omitted. If omitted, it indicates there is no HTTP request body.
 // 2. Leaf fields (recursive expansion of nested messages in the
 //    request) can be classified into three types:
 //     (a) Matched in the URL template.
@@ -218,28 +231,34 @@ message Http {
 //     FieldPath = IDENT { "." IDENT } ;
 //     Verb     = ":" LITERAL ;
 //
-// The syntax `*` matches a single path segment. It follows the semantics of
-// [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String
-// Expansion.
+// The syntax `*` matches a single path segment. The syntax `**` matches zero
+// or more path segments, which must be the last part of the path except the
+// `Verb`. The syntax `LITERAL` matches literal text in the path.
 //
-// The syntax `**` matches zero or more path segments. It follows the semantics
-// of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved
-// Expansion. NOTE: it must be the last segment in the path except the Verb.
-//
-// The syntax `LITERAL` matches literal text in the URL path.
-//
-// The syntax `Variable` matches the entire path as specified by its template;
-// this nested template must not contain further variables. If a variable
+// The syntax `Variable` matches part of the URL path as specified by its
+// template. A variable template must not contain other variables. If a variable
 // matches a single path segment, its template may be omitted, e.g. `{var}`
 // is equivalent to `{var=*}`.
 //
+// If a variable contains exactly one path segment, such as `"{var}"` or
+// `"{var=*}"`, when such a variable is expanded into a URL path, all characters
+// except `[-_.~0-9a-zA-Z]` are percent-encoded. Such variables show up in the
+// Discovery Document as `{var}`.
+//
+// If a variable contains one or more path segments, such as `"{var=foo/*}"`
+// or `"{var=**}"`, when such a variable is expanded into a URL path, all
+// characters except `[-_.~/0-9a-zA-Z]` are percent-encoded. Such variables
+// show up in the Discovery Document as `{+var}`.
+//
+// NOTE: While the single segment variable matches the semantics of
+// [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2
+// Simple String Expansion, the multi segment variable **does not** match
+// RFC 6570 Reserved Expansion. The reason is that the Reserved Expansion
+// does not expand special characters like `?` and `#`, which would lead
+// to invalid URLs.
+//
 // NOTE: the field paths in variables and in the `body` must not refer to
 // repeated fields or map fields.
-//
-// Use CustomHttpPattern to specify any HTTP method that is not included in the
-// `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for
-// a given URL path rule. The wild-card rule is useful for services that provide
-// content to Web (HTML) clients.
 message HttpRule {
   // Selects methods to which this rule applies.
   //
@@ -265,7 +284,10 @@ message HttpRule {
     // Used for updating a resource.
     string patch = 6;
 
-    // Custom pattern is used for defining custom verbs.
+    // The custom pattern is used for specifying an HTTP method that is not
+    // included in the `pattern` field, such as HEAD, or "*" to leave the
+    // HTTP method unspecified for this rule. The wild-card rule is useful
+    // for services that provide content to Web (HTML) clients.
     CustomHttpPattern custom = 8;
   }