Package api

src/google/protobuf/api.proto

Api
Method
Mixin

type Api ¶

Api is a light-weight descriptor for a protocol buffer service.

type Api struct {
    // The fully qualified name of this api, including package name
    // followed by the api's simple name.
    Name string `protobuf:"bytes,1,opt,name=name" json:"name,omitempty"`
    // The methods of this api, in unspecified order.
    Methods []*Method `protobuf:"bytes,2,rep,name=methods" json:"methods,omitempty"`
    // Any metadata attached to the API.
    Options []*google_protobuf2.Option `protobuf:"bytes,3,rep,name=options" json:"options,omitempty"`
    // A version string for this api. If specified, must have the form
    // `major-version.minor-version`, as in `1.10`. If the minor version
    // is omitted, it defaults to zero. If the entire version field is
    // empty, the major version is derived from the package name, as
    // outlined below. If the field is not empty, the version in the
    // package name will be verified to be consistent with what is
    // provided here.
    //
    // The versioning schema uses [semantic
    // versioning](http://semver.org) where the major version number
    // indicates a breaking change and the minor version an additive,
    // non-breaking change. Both version numbers are signals to users
    // what to expect from different versions, and should be carefully
    // chosen based on the product plan.
    //
    // The major version is also reflected in the package name of the
    // API, which must end in `v<major-version>`, as in
    // `google.feature.v1`. For major versions 0 and 1, the suffix can
    // be omitted. Zero major versions must only be used for
    // experimental, none-GA apis.
    //
    //
    Version string `protobuf:"bytes,4,opt,name=version" json:"version,omitempty"`
    // Source context for the protocol buffer service represented by this
    // message.
    SourceContext *google_protobuf.SourceContext `protobuf:"bytes,5,opt,name=source_context,json=sourceContext" json:"source_context,omitempty"`
    // Included APIs. See [Mixin][].
    Mixins []*Mixin `protobuf:"bytes,6,rep,name=mixins" json:"mixins,omitempty"`
    // The source syntax of the service.
    Syntax google_protobuf2.Syntax `protobuf:"varint,7,opt,name=syntax,enum=google.protobuf.Syntax" json:"syntax,omitempty"`
}

func (*Api) Descriptor ¶

func (*Api) Descriptor() ([]byte, []int)

func (*Api) GetMethods ¶

func (m *Api) GetMethods() []*Method

func (*Api) GetMixins ¶

func (m *Api) GetMixins() []*Mixin

func (*Api) GetName ¶

func (m *Api) GetName() string

func (*Api) GetOptions ¶

func (m *Api) GetOptions() []*google_protobuf2.Option

func (*Api) GetSourceContext ¶

func (m *Api) GetSourceContext() *google_protobuf.SourceContext

func (*Api) GetSyntax ¶

func (m *Api) GetSyntax() google_protobuf2.Syntax

func (*Api) GetVersion ¶

func (m *Api) GetVersion() string

func (*Api) ProtoMessage ¶

func (*Api) ProtoMessage()

func (*Api) Reset ¶

func (m *Api) Reset()

func (*Api) String ¶

func (m *Api) String() string

type Method ¶

Method represents a method of an api.

type Method struct {
    // The simple name of this method.
    Name string `protobuf:"bytes,1,opt,name=name" json:"name,omitempty"`
    // A URL of the input message type.
    RequestTypeUrl string `protobuf:"bytes,2,opt,name=request_type_url,json=requestTypeUrl" json:"request_type_url,omitempty"`
    // If true, the request is streamed.
    RequestStreaming bool `protobuf:"varint,3,opt,name=request_streaming,json=requestStreaming" json:"request_streaming,omitempty"`
    // The URL of the output message type.
    ResponseTypeUrl string `protobuf:"bytes,4,opt,name=response_type_url,json=responseTypeUrl" json:"response_type_url,omitempty"`
    // If true, the response is streamed.
    ResponseStreaming bool `protobuf:"varint,5,opt,name=response_streaming,json=responseStreaming" json:"response_streaming,omitempty"`
    // Any metadata attached to the method.
    Options []*google_protobuf2.Option `protobuf:"bytes,6,rep,name=options" json:"options,omitempty"`
    // The source syntax of this method.
    Syntax google_protobuf2.Syntax `protobuf:"varint,7,opt,name=syntax,enum=google.protobuf.Syntax" json:"syntax,omitempty"`
}

func (*Method) Descriptor ¶

func (*Method) Descriptor() ([]byte, []int)

func (*Method) GetName ¶

func (m *Method) GetName() string

func (*Method) GetOptions ¶

func (m *Method) GetOptions() []*google_protobuf2.Option

func (*Method) GetRequestStreaming ¶

func (m *Method) GetRequestStreaming() bool

func (*Method) GetRequestTypeUrl ¶

func (m *Method) GetRequestTypeUrl() string

func (*Method) GetResponseStreaming ¶

func (m *Method) GetResponseStreaming() bool

func (*Method) GetResponseTypeUrl ¶

func (m *Method) GetResponseTypeUrl() string

func (*Method) GetSyntax ¶

func (m *Method) GetSyntax() google_protobuf2.Syntax

func (*Method) ProtoMessage ¶

func (*Method) ProtoMessage()

func (*Method) Reset ¶

func (m *Method) Reset()

func (*Method) String ¶

func (m *Method) String() string

type Mixin ¶

Declares an API to be included in this API. The including API must redeclare all the methods from the included API, but documentation and options are inherited as follows:

- If after comment and whitespace stripping, the documentation

string of the redeclared method is empty, it will be inherited
from the original method.

- Each annotation belonging to the service config (http,

visibility) which is not set in the redeclared method will be
inherited.

- If an http annotation is inherited, the path pattern will be

modified as follows. Any version prefix will be replaced by the
version of the including API plus the [root][] path if specified.

Example of a simple mixin:

package google.acl.v1;
service AccessControl {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v1/{resource=**}:getAcl";
  }
}

package google.storage.v2;
service Storage {
  rpc GetAcl(GetAclRequest) returns (Acl);

  // Get a data record.
  rpc GetData(GetDataRequest) returns (Data) {
    option (google.api.http).get = "/v2/{resource=**}";
  }
}

Example of a mixin configuration:

apis:
- name: google.storage.v2.Storage
  mixins:
  - name: google.acl.v1.AccessControl

The mixin construct implies that all methods in `AccessControl` are also declared with same name and request/response types in `Storage`. A documentation generator or annotation processor will see the effective `Storage.GetAcl` method after inherting documentation and annotations as follows:

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/{resource=**}:getAcl";
  }
  ...
}

Note how the version in the path pattern changed from `v1` to `v2`.

If the `root` field in the mixin is specified, it should be a relative path under which inherited HTTP paths are placed. Example:

apis:
- name: google.storage.v2.Storage
  mixins:
  - name: google.acl.v1.AccessControl
    root: acls

This implies the following inherited HTTP annotation:

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
  }
  ...
}

type Mixin struct {
    // The fully qualified name of the API which is included.
    Name string `protobuf:"bytes,1,opt,name=name" json:"name,omitempty"`
    // If non-empty specifies a path under which inherited HTTP paths
    // are rooted.
    Root string `protobuf:"bytes,2,opt,name=root" json:"root,omitempty"`
}

func (*Mixin) Descriptor ¶

func (*Mixin) Descriptor() ([]byte, []int)

func (*Mixin) GetName ¶

func (m *Mixin) GetName() string

func (*Mixin) GetRoot ¶

func (m *Mixin) GetRoot() string

func (*Mixin) ProtoMessage ¶

func (*Mixin) ProtoMessage()

func (*Mixin) Reset ¶

func (m *Mixin) Reset()

func (*Mixin) String ¶

func (m *Mixin) String() string