blob: ce07aa14f54feec4c107cdde161395ad2fb42e2e [file] [log] [blame]
Zsolt Haraszti034db372016-10-03 22:26:41 -07001// Copyright (c) 2015, Google Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.api;
18
19option java_multiple_files = true;
20option java_outer_classname = "HttpProto";
21option java_package = "com.google.api";
22
23
24// `HttpRule` defines the mapping of an RPC method to one or more HTTP REST API
25// methods. The mapping determines what portions of the request message are
26// populated from the path, query parameters, or body of the HTTP request. The
27// mapping is typically specified as an `google.api.http` annotation, see
28// "google/api/annotations.proto" for details.
29//
30// The mapping consists of a mandatory field specifying a path template and an
31// optional `body` field specifying what data is represented in the HTTP request
32// body. The field name for the path indicates the HTTP method. Example:
33//
34// ```
35// package google.storage.v2;
36//
37// import "google/api/annotations.proto";
38//
39// service Storage {
40// rpc CreateObject(CreateObjectRequest) returns (Object) {
41// option (google.api.http) {
42// post: "/v2/{bucket_name=buckets/*}/objects"
43// body: "object"
44// };
45// };
46// }
47// ```
48//
49// Here `bucket_name` and `object` bind to fields of the request message
50// `CreateObjectRequest`.
51//
52// The rules for mapping HTTP path, query parameters, and body fields
53// to the request message are as follows:
54//
55// 1. The `body` field specifies either `*` or a field path, or is
56// omitted. If omitted, it assumes there is no HTTP body.
57// 2. Leaf fields (recursive expansion of nested messages in the
58// request) can be classified into three types:
59// (a) Matched in the URL template.
60// (b) Covered by body (if body is `*`, everything except (a) fields;
61// else everything under the body field)
62// (c) All other fields.
63// 3. URL query parameters found in the HTTP request are mapped to (c) fields.
64// 4. Any body sent with an HTTP request can contain only (b) fields.
65//
66// The syntax of the path template is as follows:
67//
68// Template = "/" Segments [ Verb ] ;
69// Segments = Segment { "/" Segment } ;
70// Segment = "*" | "**" | LITERAL | Variable ;
71// Variable = "{" FieldPath [ "=" Segments ] "}" ;
72// FieldPath = IDENT { "." IDENT } ;
73// Verb = ":" LITERAL ;
74//
75// `*` matches a single path component, `**` zero or more path components, and
76// `LITERAL` a constant. A `Variable` can match an entire path as specified
77// again by a template; this nested template must not contain further variables.
78// If no template is given with a variable, it matches a single path component.
79// The notation `{var}` is henceforth equivalent to `{var=*}`.
80//
81// Use CustomHttpPattern to specify any HTTP method that is not included in the
82// pattern field, such as HEAD, or "*" to leave the HTTP method unspecified for
83// a given URL path rule. The wild-card rule is useful for services that provide
84// content to Web (HTML) clients.
85message HttpRule {
86
87 // Determines the URL pattern is matched by this rules. This pattern can be
88 // used with any of the {get|put|post|delete|patch} methods. A custom method
89 // can be defined using the 'custom' field.
90 oneof pattern {
91 // Used for listing and getting information about resources.
92 string get = 2;
93
94 // Used for updating a resource.
95 string put = 3;
96
97 // Used for creating a resource.
98 string post = 4;
99
100 // Used for deleting a resource.
101 string delete = 5;
102
103 // Used for updating a resource.
104 string patch = 6;
105
106 // Custom pattern is used for defining custom verbs.
107 CustomHttpPattern custom = 8;
108 }
109
110 // The name of the request field whose value is mapped to the HTTP body, or
111 // `*` for mapping all fields not captured by the path pattern to the HTTP
112 // body.
113 string body = 7;
114
115 // Additional HTTP bindings for the selector. Nested bindings must not
116 // specify a selector and must not contain additional bindings.
117 repeated HttpRule additional_bindings = 11;
118}
119
120// A custom pattern is used for defining custom HTTP verb.
121message CustomHttpPattern {
122 // The name of this custom HTTP verb.
123 string kind = 1;
124
125 // The path matched by this custom verb.
126 string path = 2;
127}