google-api-ruby-client/generated/google-apis-apigateway_v1/OVERVIEW.md

97 lines
6.0 KiB
Markdown
Raw Normal View History

# Simple REST client for version V1 of the API Gateway API
This is a simple client library for version V1 of the API Gateway API. It provides:
* A client object that connects to the HTTP/JSON REST endpoint for the service.
* Ruby objects for data structures related to the service.
* Integration with the googleauth gem for authentication using OAuth, API keys, and service accounts.
* Control of retry, pagination, and timeouts.
Note that although this client library is supported and will continue to be updated to track changes to the service, it is otherwise considered complete and not under active development. Many Google services, especially Google Cloud Platform services, may provide a more modern client that is under more active development and improvement. See the section below titled *Which client should I use?* for more information.
## Getting started
### Before you begin
There are a few setup steps you need to complete before you can use this library:
1. If you don't already have a Google account, [sign up](https://www.google.com/accounts).
2. If you have never created a Google APIs Console project, read about [Managing Projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects) and create a project in the [Google API Console](https://console.cloud.google.com/).
3. Most APIs need to be enabled for your project. [Enable it](https://console.cloud.google.com/apis/library/apigateway.googleapis.com) in the console.
### Installation
Add this line to your application's Gemfile:
```ruby
gem 'google-apis-apigateway_v1', '~> 0.1'
```
And then execute:
```
$ bundle
```
Or install it yourself as:
```
$ gem install google-apis-apigateway_v1
```
### Creating a client object
Once the gem is installed, you can load the client code and instantiate a client.
```ruby
# Load the client
require "google/apis/apigateway_v1"
# Create a client object
client = Google::Apis::ApigatewayV1::ApigatewayService.new
# Authenticate calls
client.authentication = # ... use the googleauth gem to create credentials
```
See the class reference docs for information on the methods you can call from a client.
## Documentation
More detailed descriptions of the Google simple REST clients are available in two documents.
* The [Usage Guide](https://github.com/googleapis/google-api-ruby-client/blob/master/docs/usage-guide.md) discusses how to make API calls, how to use the provided data structures, and how to work the various features of the client library, including media upload and download, error handling, retries, pagination, and logging.
* The [Auth Guide](https://github.com/googleapis/google-api-ruby-client/blob/master/docs/auth-guide.md) discusses authentication in the client libraries, including API keys, OAuth 2.0, service accounts, and environment variables.
(Note: the above documents are written for the simple REST clients in general, and their examples may not reflect the Apigateway service in particular.)
For reference information on specific calls in the API Gateway API, see the {Google::Apis::ApigatewayV1::ApigatewayService class reference docs}.
## Which client should I use?
Google provides two types of Ruby API client libraries: **simple REST clients** and **modern clients**.
This library, `google-apis-apigateway_v1`, is a simple REST client. You can identify these clients by their gem names, which are always in the form `google-apis-<servicename>_<serviceversion>`. The simple REST clients connect to HTTP/JSON REST endpoints and are automatically generated from service discovery documents. They support most API functionality, but their class interfaces are sometimes awkward.
Modern clients are produced by a modern code generator, sometimes combined with hand-crafted functionality. Most modern clients connect to high-performance gRPC endpoints, although a few are backed by REST services. Modern clients are available for many Google services, especially Google Cloud Platform services, but do not yet support all the services covered by the simple clients.
Gem names for modern clients are often of the form `google-cloud-<service_name>`. (For example, [google-cloud-pubsub](https://rubygems.org/gems/google-cloud-pubsub).) Note that most modern clients also have corresponding "versioned" gems with names like `google-cloud-<service_name>-<version>`. (For example, [google-cloud-pubsub-v1](https://rubygems.org/gems/google-cloud-pubsub-v1).) The "versioned" gems can be used directly, but often provide lower-level interfaces. In most cases, the main gem is recommended.
**For most users, we recommend the modern client, if one is available.** Compared with simple clients, modern clients are generally much easier to use and more Ruby-like, support more advanced features such as streaming and long-running operations, and often provide much better performance. You may consider using a simple client instead, if a modern client is not yet available for the service you want to use, or if you are not able to use gRPC on your infrastructure.
feat: Automated regeneration of apigateway v1 client (#2369) This PR was generated using Autosynth. :rainbow: <details><summary>Log from Synthtool</summary> ``` 2021-01-13 01:37:56,937 synthtool [DEBUG] > Executing /home/kbuilder/.cache/synthtool/google-api-ruby-client/synth.py. On branch autosynth-apigateway-v1 nothing to commit, working tree clean 2021-01-13 01:37:57,005 synthtool [DEBUG] > Running: docker run --rm -v/home/kbuilder/.cache/synthtool/google-api-ruby-client:/workspace -v/var/run/docker.sock:/var/run/docker.sock -w /workspace --entrypoint script/synth.rb gcr.io/cloud-devrel-kokoro-resources/yoshi-ruby/autosynth apigateway v1 DEBUG:synthtool:Running: docker run --rm -v/home/kbuilder/.cache/synthtool/google-api-ruby-client:/workspace -v/var/run/docker.sock:/var/run/docker.sock -w /workspace --entrypoint script/synth.rb gcr.io/cloud-devrel-kokoro-resources/yoshi-ruby/autosynth apigateway v1 git clean -df bundle install Don't run Bundler as root. Bundler can ask for sudo if it is needed, and installing your bundle as root will break this application for all non-root users on this machine. The dependency jruby-openssl (>= 0) will be unused by any of the platforms Bundler is installing for. Bundler is installing for ruby but the dependency is only for java. To add those platforms to the bundle, run `bundle lock --add-platform java`. Fetching gem metadata from https://rubygems.org/......... Fetching gem metadata from https://rubygems.org/. Resolving dependencies... Fetching rake 11.3.0 Installing rake 11.3.0 Fetching concurrent-ruby 1.1.7 Installing concurrent-ruby 1.1.7 Fetching i18n 1.8.7 Installing i18n 1.8.7 Fetching minitest 5.14.3 Installing minitest 5.14.3 Fetching tzinfo 2.0.4 Installing tzinfo 2.0.4 Fetching zeitwerk 2.4.2 Installing zeitwerk 2.4.2 Fetching activesupport 6.1.1 Installing activesupport 6.1.1 Fetching public_suffix 4.0.6 Installing public_suffix 4.0.6 Fetching addressable 2.7.0 Installing addressable 2.7.0 Fetching ast 2.4.1 Installing ast 2.4.1 Using bundler 2.1.4 Fetching byebug 11.1.3 Installing byebug 11.1.3 with native extensions Fetching coderay 1.1.3 Installing coderay 1.1.3 Fetching json 2.5.1 Installing json 2.5.1 with native extensions Fetching docile 1.3.4 Installing docile 1.3.4 Fetching simplecov-html 0.10.2 Installing simplecov-html 0.10.2 Fetching simplecov 0.16.1 Installing simplecov 0.16.1 Using sync 0.5.0 Fetching tins 1.28.0 Installing tins 1.28.0 Fetching term-ansicolor 1.7.1 Installing term-ansicolor 1.7.1 Fetching thor 0.20.3 Installing thor 0.20.3 Fetching coveralls 0.8.23 Installing coveralls 0.8.23 Fetching rexml 3.2.4 Installing rexml 3.2.4 Fetching crack 0.4.5 Installing crack 0.4.5 Fetching declarative 0.0.20 Installing declarative 0.0.20 Fetching declarative-option 0.1.0 Installing declarative-option 0.1.0 Fetching diff-lcs 1.4.4 Installing diff-lcs 1.4.4 Fetching dotenv 2.7.6 Installing dotenv 2.7.6 Fetching fakefs 0.20.1 Installing fakefs 0.20.1 Fetching faraday-net_http 1.0.1 Installing faraday-net_http 1.0.1 Fetching multipart-post 2.1.1 Installing multipart-post 2.1.1 Fetching ruby2_keywords 0.0.2 Installing ruby2_keywords 0.0.2 Fetching faraday 1.3.0 Installing faraday 1.3.0 Fetching gems 1.2.0 Installing gems 1.2.0 Fetching github-markup 1.7.0 Installing github-markup 1.7.0 Fetching jwt 2.2.2 Installing jwt 2.2.2 Fetching memoist 0.16.2 Installing memoist 0.16.2 Fetching multi_json 1.15.0 Installing multi_json 1.15.0 Fetching os 0.9.6 Installing os 0.9.6 Fetching signet 0.14.0 Installing signet 0.14.0 Fetching googleauth 0.14.0 Installing googleauth 0.14.0 Fetching httpclient 2.8.3 Installing httpclient 2.8.3 Fetching mini_mime 1.0.2 Installing mini_mime 1.0.2 Fetching uber 0.1.0 Installing uber 0.1.0 Fetching representable 3.0.4 Installing representable 3.0.4 Fetching retriable 3.1.2 Installing retriable 3.1.2 Fetching google-apis-core 0.2.0 Installing google-apis-core 0.2.0 Fetching google-apis-discovery_v1 0.1.0 Installing google-apis-discovery_v1 0.1.0 Using google-apis-generator 0.1.1 from source at `.` Fetching google-id-token 1.4.2 Installing google-id-token 1.4.2 Fetching hashdiff 1.0.1 Installing hashdiff 1.0.1 Fetching mime-types-data 3.2020.1104 Installing mime-types-data 3.2020.1104 Fetching mime-types 3.3.1 Installing mime-types 3.3.1 Fetching multi_xml 0.6.0 Installing multi_xml 0.6.0 Fetching httparty 0.18.1 Installing httparty 0.18.1 Fetching rspec-support 3.10.1 Installing rspec-support 3.10.1 Fetching rspec-core 3.10.1 Installing rspec-core 3.10.1 Fetching rspec-expectations 3.10.1 Installing rspec-expectations 3.10.1 Fetching rspec-mocks 3.10.1 Installing rspec-mocks 3.10.1 Fetching rspec 3.10.0 Installing rspec 3.10.0 Fetching json_spec 1.1.5 Installing json_spec 1.1.5 Fetching launchy 2.5.0 Installing launchy 2.5.0 Fetching little-plugger 1.1.4 Installing little-plugger 1.1.4 Fetching logging 2.3.0 Installing logging 2.3.0 Fetching method_source 1.0.0 Installing method_source 1.0.0 Fetching opencensus 0.5.0 Installing opencensus 0.5.0 Fetching parallel 1.20.1 Installing parallel 1.20.1 Fetching parser 2.7.2.0 Installing parser 2.7.2.0 Fetching powerpack 0.1.3 Installing powerpack 0.1.3 Fetching pry 0.13.1 Installing pry 0.13.1 Fetching pry-byebug 3.9.0 Installing pry-byebug 3.9.0 Fetching yard 0.9.26 Installing yard 0.9.26 Fetching pry-doc 0.13.5 Installing pry-doc 0.13.5 Fetching rainbow 2.2.2 Installing rainbow 2.2.2 with native extensions Fetching redcarpet 3.5.1 Installing redcarpet 3.5.1 with native extensions Fetching redis 3.3.5 Installing redis 3.3.5 Fetching rmail 1.1.4 Installing rmail 1.1.4 Fetching ruby-progressbar 1.11.0 Installing ruby-progressbar 1.11.0 Fetching unicode-display_width 1.7.0 Installing unicode-display_width 1.7.0 Fetching rubocop 0.49.1 Installing rubocop 0.49.1 Fetching webmock 2.3.2 Installing webmock 2.3.2 Bundle complete! 25 Gemfile dependencies, 81 gems now installed. Use `bundle info [gemname]` to see where a bundled gem is installed. Post-install message from i18n: HEADS UP! i18n 1.1 changed fallbacks to exclude default locale. But that may break your application. If you are upgrading your Rails application from an older version of Rails: Please check your Rails app for 'config.i18n.fallbacks = true'. If you're using I18n (>= 1.1.0) and Rails (< 5.2.2), this should be 'config.i18n.fallbacks = [I18n.default_locale]'. If not, fallbacks will be broken in your app by I18n 1.1.x. If you are starting a NEW Rails application, you can ignore this notice. For more info see: https://github.com/svenfuchs/i18n/releases/tag/v1.1.0 Post-install message from httparty: When you HTTParty, you must party hard! echo a | bundle exec bin/generate-api gen /workspace/generated --api=apigateway.v1 --names=/workspace/api_names.yaml --names-out=/workspace/api_names_out.yaml --spot-check Loading apigateway, version v1 from https://raw.githubusercontent.com/googleapis/discovery-artifact-manager/master/discoveries/apigateway.v1.json conflict google-apis-apigateway_v1/OVERVIEW.md <way_v1/OVERVIEW.md? (enter "h" for help) [Ynaqdhm] a force google-apis-apigateway_v1/OVERVIEW.md conflict google-apis-apigateway_v1/lib/google/apis/apigateway_v1.rb force google-apis-apigateway_v1/lib/google/apis/apigateway_v1.rb conflict google-apis-apigateway_v1/lib/google/apis/apigateway_v1/service.rb force google-apis-apigateway_v1/lib/google/apis/apigateway_v1/service.rb conflict google-apis-apigateway_v1/lib/google/apis/apigateway_v1/gem_version.rb force google-apis-apigateway_v1/lib/google/apis/apigateway_v1/gem_version.rb conflict google-apis-apigateway_v1/CHANGELOG.md force google-apis-apigateway_v1/CHANGELOG.md Don't run Bundler as root. Bundler can ask for sudo if it is needed, and installing your bundle as root will break this application for all non-root users on this machine. The dependency jruby-openssl (>= 0) will be unused by any of the platforms Bundler is installing for. Bundler is installing for ruby but the dependency is only for java. To add those platforms to the bundle, run `bundle lock --add-platform java`. Fetching gem metadata from https://rubygems.org/......... Fetching gem metadata from https://rubygems.org/. Resolving dependencies... Fetching rake 13.0.3 Installing rake 13.0.3 Using public_suffix 4.0.6 Using addressable 2.7.0 Using bundler 2.1.4 Using declarative 0.0.20 Using declarative-option 0.1.0 Using diff-lcs 1.4.4 Using faraday-net_http 1.0.1 Using multipart-post 2.1.1 Using ruby2_keywords 0.0.2 Using faraday 1.3.0 Using jwt 2.2.2 Using memoist 0.16.2 Using multi_json 1.15.0 Fetching os 1.1.1 Installing os 1.1.1 Using signet 0.14.0 Using googleauth 0.14.0 Using httpclient 2.8.3 Using mini_mime 1.0.2 Using uber 0.1.0 Using representable 3.0.4 Using retriable 3.1.2 Using rexml 3.2.4 Using google-apis-core 0.2.0 Using google-apis-apigateway_v1 0.2.0 from source at `.` Using opencensus 0.5.0 Using redcarpet 3.5.1 Using rspec-support 3.10.1 Using rspec-core 3.10.1 Using rspec-expectations 3.10.1 Using rspec-mocks 3.10.1 Using rspec 3.10.0 Using yard 0.9.26 Bundle complete! 8 Gemfile dependencies, 33 gems now installed. Use `bundle info [gemname]` to see where a bundled gem is installed. /root/.rbenv/versions/2.6.6/bin/ruby -I/root/.rbenv/versions/2.6.6/lib/ruby/gems/2.6.0/gems/rspec-core-3.10.1/lib:/root/.rbenv/versions/2.6.6/lib/ruby/gems/2.6.0/gems/rspec-support-3.10.1/lib /root/.rbenv/versions/2.6.6/lib/ruby/gems/2.6.0/gems/rspec-core-3.10.1/exe/rspec --pattern spec/\*\*\{,/\*/\*\*\}/\*_spec.rb Google::Apis::ApigatewayV1 should load Finished in 0.29196 seconds (files took 0.10615 seconds to load) 1 example, 0 failures Files: 4 Modules: 3 ( 1 undocumented) Classes: 27 ( 0 undocumented) Constants: 5 ( 0 undocumented) Attributes: 61 ( 0 undocumented) Methods: 83 ( 0 undocumented) 99.44% documented google-apis-apigateway_v1 0.2.0 built to pkg/google-apis-apigateway_v1-0.2.0.gem. identical /workspace/api_names_out.yaml 2021-01-13 01:38:28,678 synthtool [DEBUG] > Wrote metadata to generated/google-apis-apigateway_v1/synth.metadata. DEBUG:synthtool:Wrote metadata to generated/google-apis-apigateway_v1/synth.metadata. ``` </details> Full log will be available here: https://source.cloud.google.com/results/invocations/2c9a7f94-8490-460d-bb8a-c9c25cb6fec9/targets - [ ] To automatically regenerate this PR, check this box.
2021-01-13 09:52:02 +00:00
The [product documentation](https://cloud.google.com/api-gateway/docs) may provide guidance regarding the preferred client library to use.
## Supported Ruby versions
This library is supported on Ruby 2.5+.
Google provides official support for Ruby versions that are actively supported by Ruby Core -- that is, Ruby versions that are either in normal maintenance or in security maintenance, and not end of life. Currently, this means Ruby 2.5 and later. Older versions of Ruby _may_ still work, but are unsupported and not recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details about the Ruby support schedule.
## License
This library is licensed under Apache 2.0. Full license text is available in the {file:LICENSE.md LICENSE}.
## Support
Please [report bugs at the project on Github](https://github.com/google/google-api-ruby-client/issues). Don't hesitate to [ask questions](http://stackoverflow.com/questions/tagged/google-api-ruby-client) about the client or APIs on [StackOverflow](http://stackoverflow.com).