Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document how and when the library raises exceptions #1412

Merged
merged 5 commits into from
Apr 19, 2022
Merged

Document how and when the library raises exceptions #1412

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9d11725
[ci skip] Move "SSL Connection Errors" in README Table of Contents
timrogers Apr 13, 2022
5a3fdb5
[ci skip] Rename "Quick Start" in the readme to "Installation"
timrogers Apr 13, 2022
dcaf5b1
[ci skip] Improve README heading structure
timrogers Apr 14, 2022
ec45c90
[ci skip] Document how and when the library raises exceptions
timrogers Apr 14, 2022
7b17087
Use standardised casing in "Handling errors" bullet points
timrogers Apr 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 29 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,23 +10,25 @@ 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)
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)
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)
Expand Down Expand Up @@ -66,7 +68,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

Expand All @@ -80,7 +82,7 @@ Access the library in Ruby:

require 'octokit'

### Making requests
## Making requests

[API methods][] are available as client instance methods.

Expand All @@ -95,7 +97,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:

Expand All @@ -111,7 +113,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.
Expand All @@ -134,7 +136,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
Expand All @@ -146,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
Expand Down