From 9d11725bfe30816600e17a8f423affd17b0158b6 Mon Sep 17 00:00:00 2001 From: Tim Rogers Date: Wed, 13 Apr 2022 18:31:06 +0000 Subject: [PATCH 1/5] [ci skip] Move "SSL Connection Errors" in README Table of Contents The Table of Contents in the readme has the "SSL Connection Errors" section as its own heading, when it should be under "Working with GitHub Enterprise". This fixes it. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4e1098228..e54b52116 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new 1. [Interacting with the GitHub.com APIs in GitHub Enterprise](#interacting-with-the-githubcom-apis-in-github-enterprise) 2. [Interacting with the GitHub Enterprise Admin APIs](#interacting-with-the-github-enterprise-admin-apis) 3. [Interacting with the GitHub Enterprise Management Console APIs](#interacting-with-the-github-enterprise-management-console-apis) -9. [SSL Connection Errors](#ssl-connection-errors) + 4. [SSL Connection Errors](#ssl-connection-errors) 10. [Configuration and defaults](#configuration-and-defaults) 1. [Configuring module defaults](#configuring-module-defaults) 2. [Using ENV variables](#using-env-variables) From 5a3fdb5e64a0853fbc89089ee7a6f857f7abfc6f Mon Sep 17 00:00:00 2001 From: Tim Rogers Date: Wed, 13 Apr 2022 18:36:55 +0000 Subject: [PATCH 2/5] [ci skip] Rename "Quick Start" in the readme to "Installation" --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e54b52116..607a86756 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new ## Table of Contents 1. [Philosophy](#philosophy) -2. [Quick start](#quick-start) +2. [Installation](#quick-start) 3. [Making requests](#making-requests) 4. [Consuming resources](#consuming-resources) 5. [Accessing HTTP responses](#accessing-http-responses) @@ -66,7 +66,7 @@ client.readme 'al3x/sovereign', :accept => 'application/vnd.github.html' [wrappers]: http://wynnnetherland.com/journal/what-makes-a-good-api-wrapper [github-api]: https://developer.github.com/v3/ -## Quick start +## Installation Install via Rubygems From dcaf5b16d7d034fb8d74c560bd4c75966c036547 Mon Sep 17 00:00:00 2001 From: Tim Rogers Date: Thu, 14 Apr 2022 11:03:57 +0000 Subject: [PATCH 3/5] [ci skip] Improve README heading structure --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 607a86756..9a4322084 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new 1. [Philosophy](#philosophy) 2. [Installation](#quick-start) 3. [Making requests](#making-requests) + 1. [Additional Query Parameters](#additional-query-parameters) 4. [Consuming resources](#consuming-resources) 5. [Accessing HTTP responses](#accessing-http-responses) 6. [Authentication](#authentication) @@ -80,7 +81,7 @@ Access the library in Ruby: require 'octokit' -### Making requests +## Making requests [API methods][] are available as client instance methods. @@ -95,7 +96,7 @@ client = Octokit::Client.new(:access_token => 'personal_access_token') client.user ``` -### Additional Query Parameters +### Additional query parameters When passing additional parameters to GET based request use the following syntax: @@ -111,7 +112,7 @@ When passing additional parameters to GET based request use the following syntax [API methods]: http://octokit.github.io/octokit.rb/method_list.html -### Consuming resources +## Consuming resources Most methods return a `Resource` object which provides dot notation and `[]` access for fields returned in the API response. @@ -134,7 +135,7 @@ user.rels[:gists].href **Note:** URL fields are culled into a separate `.rels` collection for easier [Hypermedia](#hypermedia-agent) support. -### Accessing HTTP responses +## Accessing HTTP responses While most methods return a `Resource` object or a Boolean, sometimes you may need access to the raw HTTP response headers. You can access the last HTTP From ec45c90ff86220604ec50566d0b3cb0a957f9ae9 Mon Sep 17 00:00:00 2001 From: Tim Rogers Date: Thu, 14 Apr 2022 11:04:28 +0000 Subject: [PATCH 4/5] [ci skip] Document how and when the library raises exceptions --- README.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9a4322084..2fdcbdbd7 100644 --- a/README.md +++ b/README.md @@ -15,15 +15,16 @@ Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new 1. [Additional Query Parameters](#additional-query-parameters) 4. [Consuming resources](#consuming-resources) 5. [Accessing HTTP responses](#accessing-http-responses) -6. [Authentication](#authentication) +6. [Handling errors](#handling-errors) +7. [Authentication](#authentication) 1. [Basic Authentication](#basic-authentication) 2. [OAuth access tokens](#oauth-access-tokens) 3. [Two-Factor Authentication](#two-factor-authentication) 4. [Using a .netrc file](#using-a-netrc-file) 5. [Application authentication](#application-authentication) -7. [Pagination](#pagination) +8. [Pagination](#pagination) 1. [Auto pagination](#auto-pagination) -8. [Working with GitHub Enterprise](#working-with-github-enterprise) +9. [Working with GitHub Enterprise](#working-with-github-enterprise) 1. [Interacting with the GitHub.com APIs in GitHub Enterprise](#interacting-with-the-githubcom-apis-in-github-enterprise) 2. [Interacting with the GitHub Enterprise Admin APIs](#interacting-with-the-github-enterprise-admin-apis) 3. [Interacting with the GitHub Enterprise Management Console APIs](#interacting-with-the-github-enterprise-management-console-apis) @@ -147,6 +148,23 @@ response = client.last_response etag = response.headers[:etag] ``` +## Handling errors + +When the API returns an error response, Octokit will raise a Ruby exception. + +A range of different exceptions can be raised depending on the error returned +by the API - for example: + +* A `400 Bad Request` response will lead to an `Octokit::BadRequest` error +* a `403 Forbidden` error with a "rate limited exceeded" message will lead + to a `Octokit::TooManyRequests` error + +All of the different exception classes inherit from `Octokit::Error` and +expose the `#response_status`, `#response_headers` and `#response_body`. +For validation errors, `#errors` will return an `Array` of `Hash`es +with the detailed information +[returned by the API](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#client-errors). + ## Authentication Octokit supports the various [authentication methods supported by the GitHub From 7b17087c95c1cb393cf2f246b5a247b22e9c69e1 Mon Sep 17 00:00:00 2001 From: Tim Rogers Date: Thu, 14 Apr 2022 15:27:30 +0100 Subject: [PATCH 5/5] Use standardised casing in "Handling errors" bullet points MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Thanks @nickfloyd 🥰! Co-authored-by: Nick Floyd <139819+nickfloyd@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2fdcbdbd7..e1e39d7b2 100644 --- a/README.md +++ b/README.md @@ -156,7 +156,7 @@ A range of different exceptions can be raised depending on the error returned by the API - for example: * A `400 Bad Request` response will lead to an `Octokit::BadRequest` error -* a `403 Forbidden` error with a "rate limited exceeded" message will lead +* A `403 Forbidden` error with a "rate limited exceeded" message will lead to a `Octokit::TooManyRequests` error All of the different exception classes inherit from `Octokit::Error` and