Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
CHTJonas committed Aug 18, 2023
1 parent 6d9dc8e commit cbfdced
Showing 1 changed file with 18 additions and 10 deletions.
28 changes: 18 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,14 @@
The Camdram gem is an API wrapper and interface for [Camdram](https://www.camdram.net) 🎭 that's made with love ❤️ and written in Ruby 💎.

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'camdram', '~> 2.0'
gem 'camdram'
```

And then execute:

```shell
bundle install
```
And then run `bundle install`.

Or install it yourself as:

Expand All @@ -29,9 +26,11 @@ gem install camdram
```

## Usage

Version 2 comes with significant backend changes which now allows you to use the [client credentials](http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.4) OAuth strategy in addition to [authorisation code](http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.1).

### Client Credentials

Use this strategy if you are writing a server-side application that accesses the Camdram API itself or on the behalf of the user who created it.

```ruby
Expand All @@ -44,6 +43,7 @@ end
```

### Authorisation Code

Use this strategy if you are authenticating a user via Camdram login and then acting on that user's behalf with an access token you already have from eg. [omniauth-camdram](https://github.com/camdram/omniauth-camdram).
You will need a hash of the access token and optionally, if you want to refresh the token after it expires, the refresh token and [Unix time](https://en.wikipedia.org/wiki/Unix_time) when the access token expires.

Expand All @@ -58,6 +58,7 @@ end
```

### Read only

It's also possible to perform read-only requests to the Camdram API without API credentials, however this is *strongly* discouraged.

```ruby
Expand All @@ -70,10 +71,12 @@ end
```

## Documentation

Full documentation is generated automatically from the source code by [YARD](https://yardoc.org) and is available to view on
[RubyDocs](https://www.rubydoc.info/gems/camdram).

## Examples

Just some of the things you can do after configuring a `client` object:
```ruby
client.user.get_shows
Expand All @@ -89,6 +92,7 @@ client.user.get_venues[0].facebook_id
```

These public read-only actions don't require an access token (although you are still strongly advised to use one anyway):

```ruby
client.get_show(6171)
client.get_show("2018-lucky")
Expand All @@ -109,6 +113,7 @@ client.get_venue("cambridge-arts-theatre").news
```

It's always a good idea to handle exceptions gracefully within your application. To that end, the Camdram gem raises the following:

```ruby
begin
blargh
Expand All @@ -125,10 +130,12 @@ end
```

## Advanced Config

Need control of the HTTP backend, timeouts, redirects, headers, logging, proxying, client certificates etc.?
The Camdram gem uses the [OAuth2](https://github.com/oauth-xx/oauth2) gem as it's backend,
which in turn uses [Faraday](https://github.com/lostisland/faraday) for making HTTP requests.
To that end, you can pass a block when instantiating a client that will be passed to the Faraday connection builder:

```ruby
require 'camdram/client'
client = Camdram::Client.new do |config|
Expand All @@ -145,10 +152,12 @@ client = Camdram::Client.new do |config|
end
end
```

Be sure to checkout the documentation for Faraday and the adapter you want to use for more complex setups than the above.
If you don't give any block when instantiating then the OAuth2/Faraday defaults will be used (Net::HTTP at the time of writing).

## Development

First download a copy of the source code:

```shell
Expand All @@ -162,6 +171,7 @@ APP_ID=yourappid APP_SECRET=yourappsecret rake test
```

## Contributing

Bug reports, enhancements and pull requests are welcome on [GitHub](https://github.com/CHTJonas/camdram-ruby)!
If you think this is something you can do yourself:
1. Fork it ( https://github.com/CHTJonas/camdram-ruby/fork )
Expand All @@ -171,18 +181,16 @@ If you think this is something you can do yourself:
5. Create a new Pull Request

## Versioning

This library aims to adhere to [Semantic Versioning 2.0.0](http://semver.org/).
Violations of this scheme should be reported as bugs.
Specifically, if a minor or patch version is released that breaks backward compatibility,
that version should be immediately yanked and/or a new version should be immediately released that restores compatibility.
Breaking changes to the public API will only be introduced with new major versions.
As a result of this policy, you can (and should) specify a dependency on this gem using the
[Pessimistic Version Constraint](http://guides.rubygems.org/patterns/#pessimistic-version-constraint) with two digits of precision.
For example:
```ruby
spec.add_runtime_dependency 'camdram', '~> 2.0'
```

## Copyright

Copyright (c) 2018–2021 Charlie Jonas.
See [LICENSE](LICENSE) for details.

0 comments on commit cbfdced

Please sign in to comment.