legacy-libs/google-proto-files/google/api/system_parameter.proto

   1 // Copyright 2018 Google LLC.
   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 //
  15
  16 syntax = "proto3";
  17
  18 package google.api;
  19
  20 option go_package = "google.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig";
  21 option java_multiple_files = true;
  22 option java_outer_classname = "SystemParameterProto";
  23 option java_package = "com.google.api";
  24 option objc_class_prefix = "GAPI";
  25
  26 // ### System parameter configuration
  27 //
  28 // A system parameter is a special kind of parameter defined by the API
  29 // system, not by an individual API. It is typically mapped to an HTTP header
  30 // and/or a URL query parameter. This configuration specifies which methods
  31 // change the names of the system parameters.
  32 message SystemParameters {
  33   // Define system parameters.
  34   //
  35   // The parameters defined here will override the default parameters
  36   // implemented by the system. If this field is missing from the service
  37   // config, default system parameters will be used. Default system parameters
  38   // and names is implementation-dependent.
  39   //
  40   // Example: define api key for all methods
  41   //
  42   //     system_parameters
  43   //       rules:
  44   //         - selector: "*"
  45   //           parameters:
  46   //             - name: api_key
  47   //               url_query_parameter: api_key
  48   //
  49   //
  50   // Example: define 2 api key names for a specific method.
  51   //
  52   //     system_parameters
  53   //       rules:
  54   //         - selector: "/ListShelves"
  55   //           parameters:
  56   //             - name: api_key
  57   //               http_header: Api-Key1
  58   //             - name: api_key
  59   //               http_header: Api-Key2
  60   //
  61   // **NOTE:** All service configuration rules follow "last one wins" order.
  62   repeated SystemParameterRule rules = 1;
  63 }
  64
  65 // Define a system parameter rule mapping system parameter definitions to
  66 // methods.
  67 message SystemParameterRule {
  68   // Selects the methods to which this rule applies. Use '*' to indicate all
  69   // methods in all APIs.
  70   //
  71   // Refer to [selector][google.api.DocumentationRule.selector] for syntax
  72   // details.
  73   string selector = 1;
  74
  75   // Define parameters. Multiple names may be defined for a parameter.
  76   // For a given method call, only one of them should be used. If multiple
  77   // names are used the behavior is implementation-dependent.
  78   // If none of the specified names are present the behavior is
  79   // parameter-dependent.
  80   repeated SystemParameter parameters = 2;
  81 }
  82
  83 // Define a parameter's name and location. The parameter may be passed as either
  84 // an HTTP header or a URL query parameter, and if both are passed the behavior
  85 // is implementation-dependent.
  86 message SystemParameter {
  87   // Define the name of the parameter, such as "api_key" . It is case sensitive.
  88   string name = 1;
  89
  90   // Define the HTTP header name to use for the parameter. It is case
  91   // insensitive.
  92   string http_header = 2;
  93
  94   // Define the URL query parameter name to use for the parameter. It is case
  95   // sensitive.
  96   string url_query_parameter = 3;
  97 }