Step by Step Guide to Building a Linear API Integration in Ruby

Aug 13, 2024 • 5 minute read

Introduction

Hey there, fellow dev! Ready to supercharge your project management with Linear? Let's dive into building a slick API integration using Ruby and the awesome linear-cli package. Trust me, it's easier than you think!

Prerequisites

Before we jump in, make sure you've got:

A Ruby environment up and running (you've got this, right?)
A Linear account with an API key (if you don't have one, grab it from your Linear settings)

Installation

First things first, let's get that linear-cli gem installed:

gem install linear-cli

Easy peasy!

Authentication

Now, let's get you authenticated. It's as simple as setting your API key:

require 'linear'

Linear.configure do |config|
  config.api_key = 'your_api_key_here'
end

Basic API Requests

Alright, time for the fun stuff! Let's play with some issues:

Fetching issues

issues = Linear::Issue.all
puts issues.first.title

Creating issues

new_issue = Linear::Issue.create(title: 'Fix that pesky bug', description: 'It's driving me nuts!')

Updating issues

issue = Linear::Issue.find('ISSUE_ID')
issue.update(status: 'In Progress')

Advanced Usage

Ready to level up? Let's get fancy:

Querying with GraphQL

query = <<~GRAPHQL
  query {
    issues(first: 10) {
      nodes {
        id
        title
        assignee {
          name
        }
      }
    }
  }
GRAPHQL

result = Linear.client.query(query)

Handling pagination

Linear::Issue.all.auto_paginate do |issue|
  puts issue.title
end

Error handling

begin
  Linear::Issue.create(title: '')
rescue Linear::Error => e
  puts "Oops! #{e.message}"
end

Building a Custom Integration

Let's put it all together with a cool example. How about automatically creating issues from your customer support tickets?

def create_issue_from_ticket(ticket)
  Linear::Issue.create(
    title: "Support: #{ticket.subject}",
    description: ticket.description,
    labels: ['customer-support']
  )
end

# Use it like this:
support_tickets.each do |ticket|
  create_issue_from_ticket(ticket)
end

Best Practices

Keep an eye on those rate limits! Linear's pretty generous, but don't go crazy.
Batch your requests when possible to keep things speedy.

Troubleshooting

Running into issues? Here are some common gotchas:

Double-check your API key if you're getting authentication errors.
Make sure you're handling rate limits properly.
If you're not seeing expected data, check your query structure.

Conclusion

And there you have it! You're now equipped to build some seriously cool Linear integrations with Ruby. The possibilities are endless – from custom dashboards to automated workflows. Go forth and code, my friend!

Need more info? Check out the Linear API docs and the linear-cli gem documentation. Happy coding!