Learn more about the Dub.co Ruby SDK in the [official documentation](https://dub.co/docs/sdks/ruby/overview).
## Summary
Dub API: Dub is the modern link attribution platform for short links, conversion tracking, and affiliate programs.
## Table of Contents
* [SDK Installation](#sdk-installation)
* [SDK Example Usage](#sdk-example-usage)
* [Authentication](#authentication)
* [Available Resources and Operations](#available-resources-and-operations)
* [Error Handling](#error-handling)
* [Server Selection](#server-selection)
* [Development](#development)
* [Contributions](#contributions)
## SDK Installation
The SDK can be installed using [RubyGems](https://rubygems.org/):
```bash
gem install dub
```
## SDK Example Usage
### Example 1
```ruby
require 'dub'
Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::Dub.new(
security: Models::Shared::Security.new(
token: 'DUB_API_KEY'
)
)
req = Models::Operations::CreateLinkRequestBody.new(
url: 'https://google.com',
external_id: '123456',
tag_ids: [
'clux0rgak00011...',
],
test_variants: [
Models::Operations::TestVariants.new(
url: 'https://example.com/variant-1',
percentage: 50.0
),
Models::Operations::TestVariants.new(
url: 'https://example.com/variant-2',
percentage: 50.0
),
]
)
res = s.links.create(request: req)
unless res.nil?
# handle response
end
```
### Example 2
```ruby
require 'dub'
Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::Dub.new(
security: Models::Shared::Security.new(
token: 'DUB_API_KEY'
)
)
req = Models::Operations::UpsertLinkRequestBody.new(
url: 'https://google.com',
external_id: '123456',
tag_ids: [
'clux0rgak00011...',
],
test_variants: [
Models::Operations::UpsertLinkTestVariants.new(
url: 'https://example.com/variant-1',
percentage: 50.0
),
Models::Operations::UpsertLinkTestVariants.new(
url: 'https://example.com/variant-2',
percentage: 50.0
),
]
)
res = s.links.upsert(request: req)
unless res.nil?
# handle response
end
```
## Authentication
### Per-Client Security Schemes
This SDK supports the following security scheme globally:
| Name | Type | Scheme |
| ------- | ---- | ----------- |
| `token` | http | HTTP Bearer |
You can set the security parameters through the `security` optional parameter when initializing the SDK client instance. For example:
```ruby
require 'dub'
Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::Dub.new(
security: Models::Shared::Security.new(
token: 'DUB_API_KEY'
)
)
req = Models::Operations::GetLinksRequest.new(
ending_before: 'link_1KAP4CDPBSVMMBMH9XX3YZZ0Z...',
starting_after: 'link_1KAP4CDPBSVMMBMH9XX3YZZ0Z...',
page: 1.0,
page_size: 50.0
)
res = s.links.list(request: req)
unless res.nil?
# handle response
end
```
## Available Resources and Operations
Available methods
### [Analytics](docs/sdks/analytics/README.md)
* [retrieve](docs/sdks/analytics/README.md#retrieve) - Retrieve analytics for a link, a domain, or the authenticated workspace.
### [Bounties](docs/sdks/bounties/README.md)
* [list_submissions](docs/sdks/bounties/README.md#list_submissions) - List bounty submissions
* [approve_submission](docs/sdks/bounties/README.md#approve_submission) - Approve a bounty submission
* [reject_submission](docs/sdks/bounties/README.md#reject_submission) - Reject a bounty submission
### [Commissions](docs/sdks/commissions/README.md)
* [list](docs/sdks/commissions/README.md#list) - List all commissions
* [create](docs/sdks/commissions/README.md#create) - Create commission
* [update](docs/sdks/commissions/README.md#update) - Update a commission
* [update_many](docs/sdks/commissions/README.md#update_many) - Bulk update commissions
### [Customers](docs/sdks/customers/README.md)
* [list](docs/sdks/customers/README.md#list) - List all customers
* [get](docs/sdks/customers/README.md#get) - Retrieve a customer
* [delete](docs/sdks/customers/README.md#delete) - Delete a customer
* [update](docs/sdks/customers/README.md#update) - Update a customer
### [Domains](docs/sdks/domains/README.md)
* [list](docs/sdks/domains/README.md#list) - List all domains
* [create](docs/sdks/domains/README.md#create) - Create a domain
* [delete](docs/sdks/domains/README.md#delete) - Delete a domain
* [update](docs/sdks/domains/README.md#update) - Update a domain
* [register](docs/sdks/domains/README.md#register) - Register a domain
* [check_status](docs/sdks/domains/README.md#check_status) - Check the availability of one or more domains
### [EmbedTokens](docs/sdks/embedtokens/README.md)
* [referrals](docs/sdks/embedtokens/README.md#referrals) - Create a referrals embed token
### [Events](docs/sdks/events/README.md)
* [list](docs/sdks/events/README.md#list) - List all events
### [Folders](docs/sdks/folders/README.md)
* [list](docs/sdks/folders/README.md#list) - List all folders
* [create](docs/sdks/folders/README.md#create) - Create a folder
* [delete](docs/sdks/folders/README.md#delete) - Delete a folder
* [update](docs/sdks/folders/README.md#update) - Update a folder
### [Links](docs/sdks/links/README.md)
* [list](docs/sdks/links/README.md#list) - List all links
* [create](docs/sdks/links/README.md#create) - Create a link
* [count](docs/sdks/links/README.md#count) - Retrieve links count
* [get](docs/sdks/links/README.md#get) - Retrieve a link
* [delete](docs/sdks/links/README.md#delete) - Delete a link
* [update](docs/sdks/links/README.md#update) - Update a link
* [create_many](docs/sdks/links/README.md#create_many) - Bulk create links
* [delete_many](docs/sdks/links/README.md#delete_many) - Bulk delete links
* [update_many](docs/sdks/links/README.md#update_many) - Bulk update links
* [upsert](docs/sdks/links/README.md#upsert) - Upsert a link
### [PartnerApplications](docs/sdks/partnerapplications/README.md)
* [list](docs/sdks/partnerapplications/README.md#list) - List all pending partner applications
* [approve](docs/sdks/partnerapplications/README.md#approve) - Approve a partner application
* [reject](docs/sdks/partnerapplications/README.md#reject) - Reject a partner application
### [Partners](docs/sdks/partners/README.md)
* [list](docs/sdks/partners/README.md#list) - List all partners
* [create](docs/sdks/partners/README.md#create) - Create or update a partner
* [retrieve_links](docs/sdks/partners/README.md#retrieve_links) - Retrieve a partner's links.
* [create_link](docs/sdks/partners/README.md#create_link) - Create a link for a partner
* [upsert_link](docs/sdks/partners/README.md#upsert_link) - Upsert a link for a partner
* [analytics](docs/sdks/partners/README.md#analytics) - Retrieve analytics for a partner
* [ban](docs/sdks/partners/README.md#ban) - Ban a partner
* [deactivate](docs/sdks/partners/README.md#deactivate) - Deactivate a partner
### [Payouts](docs/sdks/payouts/README.md)
* [list](docs/sdks/payouts/README.md#list) - List all payouts
### [QRCodes](docs/sdks/qrcodes/README.md)
* [get](docs/sdks/qrcodes/README.md#get) - Retrieve a QR code
### [Tags](docs/sdks/tags/README.md)
* [list](docs/sdks/tags/README.md#list) - List all tags
* [create](docs/sdks/tags/README.md#create) - Create a tag
* [delete](docs/sdks/tags/README.md#delete) - Delete a tag
* [update](docs/sdks/tags/README.md#update) - Update a tag
### [Track](docs/sdks/track/README.md)
* [lead](docs/sdks/track/README.md#lead) - Track a lead
* [sale](docs/sdks/track/README.md#sale) - Track a sale
## Error Handling
Handling errors in this SDK should largely match your expectations. All operations return a response object or raise an error.
By default an API error will raise a `Errors::APIError`, which has the following properties:
| Property | Type | Description |
|----------------|-----------------------------------------|-----------------------|
| `message` | *string* | The error message |
| `status_code` | *int* | The HTTP status code |
| `raw_response` | *Faraday::Response* | The raw HTTP response |
| `body` | *string* | The response content |
When custom error responses are specified for an operation, the SDK may also throw their associated exception. You can refer to respective *Errors* tables in SDK docs for more details on possible exception types for each operation. For example, the `list` method throws the following exceptions:
| Error Type | Status Code | Content Type |
| ----------------------------------- | ----------- | ---------------- |
| Models::Errors::BadRequest | 400 | application/json |
| Models::Errors::Unauthorized | 401 | application/json |
| Models::Errors::Forbidden | 403 | application/json |
| Models::Errors::NotFound | 404 | application/json |
| Models::Errors::Conflict | 409 | application/json |
| Models::Errors::InviteExpired | 410 | application/json |
| Models::Errors::UnprocessableEntity | 422 | application/json |
| Models::Errors::RateLimitExceeded | 429 | application/json |
| Models::Errors::InternalServerError | 500 | application/json |
| Errors::APIError | 4XX, 5XX | \*/\* |
### Example
```ruby
require 'dub'
Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::Dub.new(
security: Models::Shared::Security.new(
token: 'DUB_API_KEY'
)
)
begin
req = Models::Operations::GetLinksRequest.new(
ending_before: 'link_1KAP4CDPBSVMMBMH9XX3YZZ0Z...',
starting_after: 'link_1KAP4CDPBSVMMBMH9XX3YZZ0Z...',
page: 1.0,
page_size: 50.0
)
res = s.links.list(request: req)
unless res.nil?
# handle response
end
rescue Models::Errors::BadRequest => e
# handle e.container data
raise e
rescue Models::Errors::Unauthorized => e
# handle e.container data
raise e
rescue Models::Errors::Forbidden => e
# handle e.container data
raise e
rescue Models::Errors::NotFound => e
# handle e.container data
raise e
rescue Models::Errors::Conflict => e
# handle e.container data
raise e
rescue Models::Errors::InviteExpired => e
# handle e.container data
raise e
rescue Models::Errors::UnprocessableEntity => e
# handle e.container data
raise e
rescue Models::Errors::RateLimitExceeded => e
# handle e.container data
raise e
rescue Models::Errors::InternalServerError => e
# handle e.container data
raise e
rescue Errors::APIError => e
# handle default exception
raise e
end
```
## Server Selection
### Override Server URL Per-Client
The default server can be overridden globally by passing a URL to the `server_url (String)` optional parameter when initializing the SDK client instance. For example:
```ruby
require 'dub'
Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::Dub.new(
server_url: 'https://api.dub.co',
security: Models::Shared::Security.new(
token: 'DUB_API_KEY'
)
)
req = Models::Operations::GetLinksRequest.new(
ending_before: 'link_1KAP4CDPBSVMMBMH9XX3YZZ0Z...',
starting_after: 'link_1KAP4CDPBSVMMBMH9XX3YZZ0Z...',
page: 1.0,
page_size: 50.0
)
res = s.links.list(request: req)
unless res.nil?
# handle response
end
```
# Development
## Contributions
While we value open-source contributions to this SDK, this library is generated programmatically.
Feel free to open a PR or a Github issue as a proof of concept and we'll do our best to include it in a future release!
### SDK Created by [Speakeasy](https://docs.speakeasyapi.dev/docs/using-speakeasy/client-sdks)
