### Full Example Usage

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

A complete example demonstrating the setup, API call, and expected JSON response structure for fetching people ordered by last name.

```ruby
require 'pco_api'

api = PCO::API.new(basic_auth_token: 'token', basic_auth_secret: 'secret')
api.people.v2.people.get(order: 'last_name')
```

--------------------------------

### Installation

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Installs the pco_api gem using the RubyGems package manager.

```ruby
gem install pco_api
```

--------------------------------

### Executing GET Requests

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Demonstrates how to execute GET requests for both collections (index) and single resources (show), including passing query parameters.

```ruby
# collection
api.people.v2.people.get(order: 'last_name')
# => { data: array_of_resources }

# single resource
api.people.v2.people[1].get
# => { data: resource_hash }
```

--------------------------------

### Building API Paths

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Shows how to construct API endpoints by chaining path elements as method calls on the API object.

```ruby
api.people.v2.households
# /people/v2/households
```

--------------------------------

### Executing POST Requests

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Shows how to send a POST request to create a new resource. The resource data must be wrapped in a `{ data: { ... } }` hash.

```ruby
api.people.v2.people.post(data: { type: 'Person', attributes: { first_name: 'Tim', last_name: 'Morgan' } })
# => { data: resource_hash }
```

--------------------------------

### API Authentication

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Demonstrates how to create a PCO::API object for authentication using either HTTP Basic credentials or an OAuth2 access token.

```ruby
# authenticate with HTTP Basic:
api = PCO::API.new(basic_auth_token: 'token', basic_auth_secret: 'secret')
# ...or authenticate with an OAuth2 access token (use the 'oauth2' gem to obtain the token)
api = PCO::API.new(oauth_access_token: 'token')
```

--------------------------------

### Querying Data with `can_query_by`

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Illustrates how to query a dataset based on `can_query_by` variables, using a hash for parameters.

```ruby
api.people.v2.people.get('where[membership]': 'Member')
# GET /people/v2/people?where[membership]=Member
```

--------------------------------

### Accessing Resources by ID

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Illustrates how to access a specific resource by its ID using array-like syntax (square brackets).

```ruby
api.people.v2.households[1]
# /people/v2/households/1
```

--------------------------------

### Executing PATCH Requests

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Demonstrates sending a PATCH request to update an existing resource. The resource data must be wrapped in a `{ data: { ... } }` hash.

```ruby
api.people.v2.people[1].patch(data: { type: 'Person', id: 1, attributes: { first_name: 'Tim', last_name: 'Morgan' } })
# => { data: resource_hash }
```

--------------------------------

### PCO API Error Exception Methods

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Details the methods available on exception objects raised by the PCO API Ruby library, providing access to status code, message, detailed response, and headers.

```APIDOC
status: HTTP status code returned by the server
message: The simple string message returned by the API (e.g., "Resource Not Found")
detail: The full error response returned by the API
headers: A hash of HTTP headers returned by the API
```

--------------------------------

### Executing DELETE Requests

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Shows how to send a DELETE request to remove an existing resource. This method returns `true` upon successful deletion.

```ruby
api.people.v2.people[1].delete
# => true
```

--------------------------------

### Handling Rate Limiting in PCO API Ruby

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Demonstrates how to disable the default retry behavior for TooManyRequests errors in the PCO API Ruby library, allowing for custom error handling.

```ruby
api = PCO::API.new(...)
api.retry_when_rate_limited = false
```

--------------------------------

### PCO API Ruby Error Classes

Source: https://github.com/planningcenter/pco_api_ruby/blob/main/README.md

Maps HTTP status codes to specific error classes within the PCO API Ruby library. These classes inherit from base error classes like ClientError and ServerError.

```APIDOC
PCO::API::Errors::BadRequest < PCO::API::Errors::ClientError (400)
PCO::API::Errors::Unauthorized < PCO::API::Errors::ClientError (401)
PCO::API::Errors::Forbidden < PCO::API::Errors::ClientError (403)
PCO::API::Errors::NotFound < PCO::API::Errors::ClientError (404)
PCO::API::Errors::MethodNotAllowed < PCO::API::Errors::ClientError (405)
PCO::API::Errors::UnprocessableEntity < PCO::API::Errors::ClientError (422)
PCO::API::Errors::TooManyRequests < PCO::API::Errors::ClientError (429)
PCO::API::Errors::ClientError (other 4xx)
PCO::API::Errors::InternalServerError < PCO::API::Errors::ServerError (500)
PCO::API::Errors::ServerError (other 5xx)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.