Step by Step Guide to Building a Pipefy API Integration in Go

Aug 13, 2024 • 8 minute read

Introduction

Hey there, fellow developer! Ready to dive into the world of Pipefy API integration using Go? You're in for a treat. Pipefy is a powerful process management tool, and its API opens up a whole new realm of possibilities. In this guide, we'll walk through creating a robust integration that'll have you manipulating pipes and cards like a pro.

Prerequisites

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

Go installed on your machine (you're a Go dev, right?)
A Pipefy account with an API key (if you don't have one, hop over to Pipefy and grab it)
Your favorite code editor at the ready

Setting up the project

Let's kick things off by creating a new Go project:

mkdir pipefy-integration
cd pipefy-integration
go mod init github.com/yourusername/pipefy-integration

Now, let's grab the packages we'll need:

go get github.com/go-resty/resty/v2

Authentication

First things first, let's set up our authentication. Create a new file called client.go:

package main

import (
    "github.com/go-resty/resty/v2"
)

func newClient(apiToken string) *resty.Client {
    return resty.New().
        SetHeader("Authorization", "Bearer "+apiToken).
        SetHeader("Content-Type", "application/json")
}

Making API requests

Now that we've got our client set up, let's make some requests! Here's how you can fetch a pipe:

func getPipe(client *resty.Client, pipeID int) ([]byte, error) {
    resp, err := client.R().
        SetPathParams(map[string]string{
            "id": strconv.Itoa(pipeID),
        }).
        Get("https://api.pipefy.com/pipes/{id}")

    if err != nil {
        return nil, err
    }

    return resp.Body(), nil
}

Handling responses

Let's parse that JSON response:

type Pipe struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
    // Add other fields as needed
}

func parsePipeResponse(data []byte) (*Pipe, error) {
    var pipe Pipe
    err := json.Unmarshal(data, &pipe)
    if err != nil {
        return nil, err
    }
    return &pipe, nil
}

Implementing core functionalities

Now, let's add some more meat to our integration. Here's how you can create a card:

func createCard(client *resty.Client, pipeID int, title string) ([]byte, error) {
    payload := map[string]interface{}{
        "pipe_id": pipeID,
        "title":   title,
    }

    resp, err := client.R().
        SetBody(payload).
        Post("https://api.pipefy.com/cards")

    if err != nil {
        return nil, err
    }

    return resp.Body(), nil
}

Building a simple CLI tool

Let's wrap this all up in a neat CLI package. Create a new file called main.go:

package main

import (
    "flag"
    "fmt"
    "os"
)

func main() {
    apiToken := os.Getenv("PIPEFY_API_TOKEN")
    if apiToken == "" {
        fmt.Println("Please set the PIPEFY_API_TOKEN environment variable")
        os.Exit(1)
    }

    client := newClient(apiToken)

    getPipeCmd := flag.NewFlagSet("getpipe", flag.ExitOnError)
    pipeID := getPipeCmd.Int("id", 0, "Pipe ID")

    if len(os.Args) < 2 {
        fmt.Println("Expected 'getpipe' subcommand")
        os.Exit(1)
    }

    switch os.Args[1] {
    case "getpipe":
        getPipeCmd.Parse(os.Args[2:])
        data, err := getPipe(client, *pipeID)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(1)
        }
        pipe, err := parsePipeResponse(data)
        if err != nil {
            fmt.Println("Error parsing response:", err)
            os.Exit(1)
        }
        fmt.Printf("Pipe ID: %d, Name: %s\n", pipe.ID, pipe.Name)
    default:
        fmt.Println("Expected 'getpipe' subcommand")
        os.Exit(1)
    }
}

Testing the integration

Don't forget to test your code! Here's a simple test for the getPipe function:

func TestGetPipe(t *testing.T) {
    client := newClient("your-api-token")
    data, err := getPipe(client, 12345)
    if err != nil {
        t.Fatalf("Error getting pipe: %v", err)
    }
    pipe, err := parsePipeResponse(data)
    if err != nil {
        t.Fatalf("Error parsing pipe response: %v", err)
    }
    if pipe.ID != 12345 {
        t.Errorf("Expected pipe ID 12345, got %d", pipe.ID)
    }
}

Best practices and optimization

Remember to implement rate limiting to avoid hitting API limits. You can use a package like golang.org/x/time/rate for this. Also, consider caching responses for frequently accessed data to reduce API calls.

Conclusion

And there you have it! You've just built a solid foundation for a Pipefy API integration in Go. From here, you can expand on this base, adding more functionalities like updating cards, moving them between phases, or even setting up webhooks for real-time updates.

Remember, the key to a great integration is understanding both the API you're working with and the needs of your project. Don't be afraid to dive deep into the Pipefy API docs and experiment with different endpoints.

Happy coding, and may your pipes always flow smoothly!