HttpRule class

HttpRule defines the mapping of an RPC method to one or more HTTP 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 message, as in the example below which describes a REST GET operation on a resource collection of messages:

 service Messaging {
   rpc GetMessage(GetMessageRequest) returns (Message) {
     option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";
   }
 }
 message GetMessageRequest {
   message SubMessage {
     string subfield = 1;
   }
   string message_id = 1; // mapped to the URL
   SubMessage sub = 2;    // `sub.subfield` is url-mapped
 }
 message Message {
   string text = 1; // content of the resource
 }

The same http annotation can alternatively be expressed inside the GRPC API Configuration YAML file.

 http:
   rules:
     - selector: <proto_package_name>.Messaging.GetMessage
       get: /v1/messages/{message_id}/{sub.subfield}

This definition enables an automatic, bidrectional mapping of HTTP JSON to RPC. Example:

HTTP	RPC
GET /v1/messages/123456/foo	GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))

In general, not only fields but also field paths can be referenced from a path pattern. Fields mapped to the path pattern cannot be repeated and must have a primitive (non-message) type.

Any fields in the request message which are not bound by the path pattern automatically become (optional) HTTP query 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;
   }
   string message_id = 1; // mapped to the URL
   int64 revision = 2;    // becomes a parameter
   SubMessage sub = 3;    // `sub.subfield` becomes a parameter
 }

This enables a HTTP JSON to RPC mapping as below:

HTTP	RPC
GET /v1/messages/123456?revision=2&sub.subfield=foo	GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))

Note that fields which are mapped to HTTP parameters must have a primitive type or a repeated primitive type. Message types are not allowed. In the case of a repeated type, the parameter can be repeated in the URL, as in ...?param=A&param=B.

For HTTP method kinds which allow a request body, the body field specifies the mapping. Consider a REST update method on the message resource collection:

 service Messaging {
   rpc UpdateMessage(UpdateMessageRequest) returns (Message) {
     option (google.api.http) = {
       put: "/v1/messages/{message_id}"
       body: "message"
     };
   }
 }
 message UpdateMessageRequest {
   string message_id = 1; // mapped to the URL
   Message message = 2;   // mapped to the body
 }

The following HTTP JSON to RPC mapping is enabled, where the representation of the JSON in the request body is determined by protos JSON encoding:

HTTP	RPC
PUT /v1/messages/123456 { "text": "Hi!" }	UpdateMessage(message_id: "123456" message { text: "Hi!" })

The special name * can be used in the body mapping to define that every field not bound by the path template should be mapped to the request body. This enables the following alternative definition of the update method:

 service Messaging {
   rpc UpdateMessage(Message) returns (Message) {
     option (google.api.http) = {
       put: "/v1/messages/{message_id}"
       body: "*"
     };
   }
 }
 message Message {
   string message_id = 1;
   string text = 2;
 }

The following HTTP JSON to RPC mapping is enabled:

HTTP	RPC
PUT /v1/messages/123456 { "text": "Hi!" }	UpdateMessage(message_id: "123456" text: "Hi!")

Note that when using * in the body mapping, it is not possible to have HTTP parameters, as all fields not bound by the path end in the body. This makes this option more rarely used in practice of defining REST APIs. The common usage of * is in custom methods which don't use the URL at all for transferring data.

It is possible to define multiple HTTP methods for one RPC by using the additional_bindings option. Example:

 service Messaging {
   rpc GetMessage(GetMessageRequest) returns (Message) {
     option (google.api.http) = {
       get: "/v1/messages/{message_id}"
       additional_bindings {
         get: "/v1/users/{user_id}/messages/{message_id}"
       }
     };
   }
 }
 message GetMessageRequest {
   string message_id = 1;
   string user_id = 2;
 }

This enables the following two alternative HTTP JSON to RPC mappings:

HTTP	RPC
GET /v1/messages/123456	GetMessage(message_id: "123456")
GET /v1/users/me/messages/123456	GetMessage(user_id: "me" message_id: "123456")

Rules for HTTP mapping

The rules for mapping HTTP path, query parameters, and body fields to the request message are as follows:

1. The body field specifies either * or a field path, or is 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. (b) Covered by body (if body is *, everything except (a) fields; else everything under the body field) (c) All other fields.
3. URL query parameters found in the HTTP request are mapped to (c) fields.
4. Any body sent with an HTTP request can contain only (b) fields.

The syntax of the path template is as follows:

 Template = "/" Segments [ Verb ] ;
 Segments = Segment { "/" Segment } ;
 Segment  = "*" | "**" | LITERAL | Variable ;
 Variable = "{" FieldPath [ "=" Segments ] "}" ;
 FieldPath = IDENT { "." IDENT } ;
 Verb     = ":" LITERAL ;

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 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 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.

Inheritance

• Object
• GeneratedMessage
• HttpRule

Available extensions

• GeneratedMessageGenericExtensions

Constructors

HttpRule.new({String? selector, String? get, String? put, String? post, String? delete, String? patch, String? body, CustomHttpPattern? custom, Iterable<HttpRule>? additionalBindings, String? responseBody})

factory

HttpRule.fromBuffer(List<int> i, [ExtensionRegistry r = $pb.ExtensionRegistry.EMPTY])

factory

HttpRule.fromJson(String i, [ExtensionRegistry r = $pb.ExtensionRegistry.EMPTY])

factory

Properties

additionalBindings → PbList<HttpRule>

Additional HTTP bindings for the selector. Nested bindings must not contain an additional_bindings field themselves (that is, the nesting may only be one level deep).

no setter

body ↔ String

The name of the request field whose value is mapped to the HTTP body, or * for mapping all fields not captured by the path pattern to the HTTP body. NOTE: the referred field must not be a repeated field and must be present at the top-level of request message type.

getter/setter pair

custom ↔ CustomHttpPattern

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.

getter/setter pair

delete ↔ String

Used for deleting a resource.

getter/setter pair

get ↔ String

Used for listing and getting information about resources.

getter/setter pair

hashCode → int

Calculates a hash code based on the contents of the protobuf.

no setter, inherited

info_ → BuilderInfo

no setter, override

isFrozen → bool

Returns true if this message is marked read-only. Otherwise false.

no setter, inherited

patch ↔ String

Used for updating a resource.

getter/setter pair

post ↔ String

Used for creating a resource.

getter/setter pair

put ↔ String

Used for updating a resource.

getter/setter pair

responseBody ↔ String

Optional. The name of the response field whose value is mapped to the HTTP body of response. Other response fields are ignored. When not set, the response message will be used as HTTP body of response.

getter/setter pair

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

selector ↔ String

Selects methods to which this rule applies.

getter/setter pair

unknownFields → UnknownFieldSet

no setter, inherited

Methods

addExtension(Extension extension, Object? value) → void

Adds an extension field value to a repeated field.

inherited

check() → void

Throws a StateError if the message has required fields without a value.

inherited

clear() → void

Clears all data that was set in this message.

inherited

clearBody() → void

clearCustom() → void

clearDelete() → void

clearExtension(Extension extension) → void

Clears an extension field and also removes the extension.

inherited

clearField(int tagNumber) → void

Clears the contents of a given field.

inherited

clearGet() → void

clearPatch() → void

clearPattern() → void

clearPost() → void

clearPut() → void

clearResponseBody() → void

clearSelector() → void

clone() → HttpRule

Creates a deep copy of the fields in this message. (The generated code uses mergeFromMessage.)

override

copyWith(void updates(HttpRule)) → HttpRule

Apply updates to a copy of this message.

override

createEmptyInstance() → HttpRule

Creates an empty instance of the same message type as this.

override

deepCopy() → T

Available on T, provided by the GeneratedMessageGenericExtensions extension

Returns a writable deep copy of this message.

ensureCustom() → CustomHttpPattern

extensionsAreInitialized() → bool

inherited

freeze() → GeneratedMessage

Make this message read-only.

inherited

getDefaultForField(int tagNumber) → dynamic

Returns the default value for the given field.

inherited

getExtension(Extension extension) → dynamic

Returns the value of extension.

inherited

getField(int tagNumber) → dynamic

Returns the value of the field associated with tagNumber, or the default value if it is not set.

inherited

getFieldOrNull(int tagNumber) → dynamic

Returns the value of a field, ignoring any defaults.

inherited

getTagNumber(String fieldName) → int?

inherited

hasBody() → bool

hasCustom() → bool

hasDelete() → bool

hasExtension(Extension extension) → bool

Returns true if a value of extension is present.

inherited

hasField(int tagNumber) → bool

Whether this message has a field associated with tagNumber.

inherited

hasGet() → bool

hasPatch() → bool

hasPost() → bool

hasPut() → bool

hasRequiredFields() → bool

Whether the message has required fields.

inherited

hasResponseBody() → bool

hasSelector() → bool

isInitialized() → bool

Whether all required fields in the message and embedded messages are set.

inherited

mergeFromBuffer(List<int> input, [ExtensionRegistry extensionRegistry = ExtensionRegistry.EMPTY]) → void

Merges serialized protocol buffer data into this message.

inherited

mergeFromCodedBufferReader(CodedBufferReader input, [ExtensionRegistry extensionRegistry = ExtensionRegistry.EMPTY]) → void

Same as mergeFromBuffer, but takes a CodedBufferReader input.

inherited

mergeFromJson(String data, [ExtensionRegistry extensionRegistry = ExtensionRegistry.EMPTY]) → void

Merges field values from data, a JSON object, encoded as described by GeneratedMessage.writeToJson.

inherited

mergeFromJsonMap(Map<String, dynamic> json, [ExtensionRegistry extensionRegistry = ExtensionRegistry.EMPTY]) → void

Merges field values from a JSON object represented as a Dart map.

inherited

mergeFromMessage(GeneratedMessage other) → void

Merges the contents of the other into this message.

inherited

mergeFromProto3Json(Object? json, {TypeRegistry typeRegistry = const TypeRegistry.empty(), bool ignoreUnknownFields = false, bool supportNamesWithUnderscores = true, bool permissiveEnums = false}) → void

Merges field values from json, a JSON object using proto3 encoding.

inherited

mergeUnknownFields(UnknownFieldSet unknownFieldSet) → void

inherited

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

rebuild(void updates(T)) → T

Available on T, provided by the GeneratedMessageGenericExtensions extension

Apply updates to a copy of this message.

setExtension(Extension extension, Object value) → void

Sets the value of a non-repeated extension field to value.

inherited

setField(int tagNumber, Object value) → void

Sets the value of a field by its tagNumber.

inherited

toBuilder() → GeneratedMessage

Creates a writable, shallow copy of this message.

inherited

toDebugString() → String

Returns a String representation of this message.

inherited

toProto3Json({TypeRegistry typeRegistry = const TypeRegistry.empty()}) → Object?

Returns an Object representing Proto3 JSON serialization of this.

inherited

toString() → String

Returns a String representation of this message.

inherited

whichPattern() → HttpRule_Pattern

writeToBuffer() → Uint8List

Serialize the message as the protobuf binary format.

inherited

writeToCodedBufferWriter(CodedBufferWriter output) → void

Same as writeToBuffer, but serializes to the given CodedBufferWriter.

inherited

writeToJson() → String

Returns a JSON string that encodes this message.

inherited

writeToJsonMap() → Map<String, dynamic>

Returns the JSON encoding of this message as a Dart Map.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

create() → HttpRule

createRepeated() → PbList<HttpRule>

getDefault() → HttpRule