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

Aug 17, 2024 • 6 minute read

Introduction

Hey there, fellow Go enthusiast! Ready to dive into the world of recruitment automation? Today, we're going to build a nifty integration with the Recruitee API using our beloved Go. This powerful combo will let you streamline your hiring process and make your life a whole lot easier. Let's get cracking!

Prerequisites

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

Go installed on your machine (if not, head over to golang.org and sort that out)
Recruitee API credentials (you'll need these to authenticate your requests)

Setting up the project

First things first, let's create a new Go module:

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

Now, let's grab the HTTP client we'll be using:

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

Authentication

Recruitee uses API tokens for authentication. You'll need to grab yours from your Recruitee account. Once you've got it, let's set it up in our code:

package main

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

const (
    baseURL = "https://api.recruitee.com/c/YOUR_COMPANY_ID"
    apiToken = "YOUR_API_TOKEN"
)

func main() {
    client := resty.New()
    client.SetHeader("Authorization", "Bearer "+apiToken)
    client.SetHostURL(baseURL)
}

Making API requests

Now that we're all set up, let's make some requests! Here's how you can fetch candidates:

resp, err := client.R().
    SetResult([]map[string]interface{}{}).
    Get("/candidates")

if err != nil {
    log.Fatalf("Error fetching candidates: %v", err)
}

candidates := resp.Result().(*[]map[string]interface{})
fmt.Printf("Fetched %d candidates\n", len(*candidates))

And here's how you can create a new candidate:

newCandidate := map[string]interface{}{
    "name": "John Doe",
    "email": "[email protected]",
}

resp, err := client.R().
    SetBody(map[string]interface{}{"candidate": newCandidate}).
    SetResult(map[string]interface{}{}).
    Post("/candidates")

if err != nil {
    log.Fatalf("Error creating candidate: %v", err)
}

createdCandidate := resp.Result().(*map[string]interface{})
fmt.Printf("Created candidate with ID: %v\n", (*createdCandidate)["id"])

Handling responses

Recruitee returns JSON responses, which we're parsing directly into Go maps. For more complex applications, you might want to define structs for your data:

type Candidate struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

Don't forget to handle errors gracefully:

if resp.IsError() {
    log.Fatalf("API error: %v", resp.Error())
}

Implementing key Recruitee API endpoints

We've covered candidates, but don't forget about jobs and applications! The process is similar for these endpoints. For example, to fetch jobs:

resp, err := client.R().
    SetResult([]map[string]interface{}{}).
    Get("/jobs")

Building a simple CLI tool

Let's wrap this all up in a simple CLI tool:

package main

import (
    "flag"
    "fmt"
    "log"

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

func main() {
    action := flag.String("action", "", "Action to perform (list-candidates, create-candidate)")
    flag.Parse()

    client := resty.New()
    client.SetHeader("Authorization", "Bearer "+apiToken)
    client.SetHostURL(baseURL)

    switch *action {
    case "list-candidates":
        listCandidates(client)
    case "create-candidate":
        createCandidate(client)
    default:
        log.Fatalf("Unknown action: %s", *action)
    }
}

func listCandidates(client *resty.Client) {
    // Implementation here
}

func createCandidate(client *resty.Client) {
    // Implementation here
}

Testing the integration

Don't forget to test your code! Here's a simple example:

func TestListCandidates(t *testing.T) {
    client := resty.New()
    client.SetHeader("Authorization", "Bearer "+apiToken)
    client.SetHostURL(baseURL)

    resp, err := client.R().
        SetResult([]map[string]interface{}{}).
        Get("/candidates")

    assert.NoError(t, err)
    assert.Equal(t, 200, resp.StatusCode())
}

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.

Consider caching responses for frequently accessed data to reduce API calls.

Conclusion

And there you have it! You've just built a Recruitee API integration in Go. Pretty cool, right? From here, you can expand on this foundation to create more complex integrations. The sky's the limit!

Resources

Happy coding, and may your hiring process be ever smooth and efficient!