Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/afomera/fathom_api
A ruby gem for using the https://usefathom.com api
https://github.com/afomera/fathom_api
hacktoberfest ruby
Last synced: 3 days ago
JSON representation
A ruby gem for using the https://usefathom.com api
- Host: GitHub
- URL: https://github.com/afomera/fathom_api
- Owner: afomera
- License: mit
- Created: 2021-08-16T20:26:25.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2022-05-26T16:54:33.000Z (over 2 years ago)
- Last Synced: 2024-09-19T15:38:23.681Z (16 days ago)
- Topics: hacktoberfest, ruby
- Language: Ruby
- Homepage:
- Size: 40 KB
- Stars: 18
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Fathom API
### 🛠 An easy to use client with the Fathom API
You'll need a usefathom.com account to use the API, if you don't have one [click here to sign up](https://usefathom.com/ref/CVNWHD).
As of August 17th, 2021 the API was still early-access, so some endpoints may be different than in production. Feel free to submit a PR or issue. Contributions are welcome!
[](https://github.com/afomera/fathom_api/actions) [](https://badge.fury.io/rb/fathom_api)
## Installation
Add `fathom_api` to your application's Gemfile:
```bash
bundle add fathom_api
# OR in the Gemfile
gem "fathom_api"
```
## Usage
Create a client to get started, passing an `api_key` you generate in your Fathom API settings.
```ruby
client = Fathom::Client.new(api_key: ENV['FATHOM_API_KEY'])
```
### Fetch account details
```ruby
# Get account details
client.account.info
# => Fathom::Account
```
Responses are wrapped in an object that dynamically allows you to call the attributes as if they are an OpenStruct... IE
```ruby
response = client.account.info
# => #>
response.name
# => "Your account name"
response.email
# => "[email protected]"
```
### Pagination
When an API's response comes back with a object of "list", we automatically wrap that to attempt to provide some helper methods to ease your implementations.
```ruby
list = client.sites.list(limit: 1)
# => Fathom::List
# We provide two helper methods to allow you to get the first or last id from the data response
list.first_id
list.last_id
# check if the list has more after it with
list.has_more?
# => true
# use the next page cursor in your next response
list2 = client.sites.list(limit: 1, starting_after: list.last_id)
```
### Sites
```ruby
client.sites.list
# Optionally, pass params in to filter / limit responses
# Limit can be between 1 and 100
client.sites.list(limit: 1, starting_after: "SITE_ID")
# => Fathom::List
client.sites.retrieve(site_id: site_id)
client.sites.create({}) # Include `name` and other params
client.sites.update(site_id: site_id, {}) # Params being updated
client.sites.delete(site_id: site_id)
client.sites.wipe(site_id: site_id)
# All return
# => Fathom::Site
```
### Events
```ruby
client.events.list(site_id: site_id)
# => Fathom::List
# Optionally, pass params in to filter / limit responses
# Limit can be between 1 and 100
client.events.list(site_id: site_id, limit: 10, starting_after: "EVENT_ID")
# => Fathom::List
client.events.retrieve(site_id: site_id, event_id: event_id)
client.events.create(site_id: site_id, {}) # Attributes for event
client.events.update(site_id: site_id, {}) # Attributes being updated
client.events.delete(site_id: site_id, event_id: event_id)
client.events.wipe(site_id: site_id, event_id: event_id)
# All return
# Fathom::Event
```
### Current Visitors
```ruby
client.current_visitors(site_id: site_id, {}) # Can add detailed: true for a more detailed report
```
### Aggregation
```ruby
client.aggregations.list(entity_id: entity_id, entity: entity, aggregates: aggregates, **params)
```
You can find all the available parameters in the [official Fathom docs](https://usefathom.com/api#introduction)
## 🙏 Contributing
This project uses Standard for formatting Ruby code. Please make sure to run standardrb before submitting pull requests. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/afomera/fathom_api/blob/main/CODE_OF_CONDUCT.md).
## Code of Conduct
Everyone interacting in the FathomApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/afomera/fathom_api/blob/main/CODE_OF_CONDUCT.md).
## 📝 License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).