# Ruby on Rails

> Learn how to integrate Dub with Ruby on Rails.

import Prerequisites from "/snippets/sdk-prerequisites.mdx";
import LinkArguments from "/snippets/link-arguments.mdx";

<Prerequisites />

## 2. Install and initialize the Dub Ruby SDK

<Steps titleSize="h3">

<Step title="Install">

To install the [Dub Ruby SDK](https://dub.co/sdks/ruby), run the following command:

```bash bash
gem install dub
```

</Step>

<Step title="Initialize">

Initialize the Dub Ruby SDK by creating a new instance of the `Dub` struct.

```ruby
class LinksController < ApplicationController
  require 'dub'

  before_action :initialize_dub

  def initialize_dub
    @dub = ::OpenApiSDK::Dub.new
    @dub.config_security(
      ::OpenApiSDK::Shared::Security.new(
        token: ENV['DUB_API_KEY']
      )
    )
  end
end
```

</Step>

</Steps>

## 3. Create link

Let's create a short link using the [Dub Ruby SDK](https://dub.co/sdks/ruby).

```ruby links_controller.rb
def create
  req = ::OpenApiSDK::Operations::CreateLinkRequest.new(
    request_body: ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
      url: 'https://google.com'
    )
  )

  res = @dub.links.create(req)

  render json: res.raw_response.body
end
```

<Accordion title="Full list of available attributes for the Link model">
  <LinkArguments />
</Accordion>

Optionally, you can also pass an `externalId` field which is a unique identifier for the link in your own database to associate it with the link in Dub's system.

```ruby links_controller.rb
def create
  req = ::OpenApiSDK::Operations::CreateLinkRequest.new(
    request_body: ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
      url: 'https://google.com',
      external_id: '12345'
    )
  )

  res = @dub.links.create(req)

  render json: res.raw_response.body
end
```

This will let you easily [update the link](#5-update-link) or [retrieve analytics](#6-retrieve-analytics-for-link) for it later on using the `externalId` instead of the Dub `linkId`.

## 4. Upsert link

Dub Ruby SDK provides a method to upsert a link – where an existing link is updated if it exists, or a new link is created if it doesn't. so you don't have to worry about checking if the link already exists.

```ruby links_controller.rb
def upsert
  req = ::OpenApiSDK::Operations::UpsertLinkRequest.new(
    request_body: ::OpenApiSDK::Operations::UpsertLinkRequestBody.new(
      url: "https://google.com",
    ),
  )

  res = @dub.links.upsert(req)

  render json: res.raw_response.body
end
```

This way, you won't have to worry about checking if the link already exists when you're creating it.

## 5. Update link

Let's update an existing link using the Dub Ruby SDK.

You can do that in two ways:

- Using the link's `linkId` in Dub's system.
- Using the link's `externalId` in your own database (prefixed with `ext_`).

```ruby links_controller.rb
def update
  req = ::OpenApiSDK::Operations::UpdateLinkRequest.new(
    link_id: 'clx1gvi9o0005hf5momm6f7hj',
    request_body: ::OpenApiSDK::Operations::UpdateLinkRequestBody.new(
      url: 'https://google.uk'
    )
  )

  res = @dub.links.update(req)

  render json: res.raw_response.body
end
```

## 6. Retrieve analytics for link

Let's retrieve analytics for a link using the Dub Ruby SDK.

```ruby index.rb
def analytics
  req = ::OpenApiSDK::Operations::RetrieveAnalyticsRequest.new(
    link_id: "clx1gvi9o0005hf5momm6f7hj",
    interval: ::OpenApiSDK::Operations::Interval::SEVEND,
    group_by: ::OpenApiSDK::Operations::GroupBy::TIMESERIES
  )

  res = @dub.analytics.retrieve(req)

  render json: res.raw_response.body
end
```

## 7. Examples

<CardGroup cols={2}>
  <Card
    title="Rails Example"
    icon="github"
    href="https://github.com/dubinc/examples/tree/main/ruby/rails/example"
    color="#333333"
  >
    See the full example on GitHub.
  </Card>
</CardGroup>