apideck-libraries/apideck-go

Apideck Go SDK Skill

Overview

The Apideck Unified API provides a single integration layer to connect with 200+ third-party services across accounting, CRM, HRIS, file storage, ATS, e-commerce, and more. The official Go SDK provides typed clients for all unified APIs.

Installation

go get github.com/apideck-libraries/sdk-go

IMPORTANT RULES

• ALWAYS use the github.com/apideck-libraries/sdk-go SDK. DO NOT make raw net/http calls to the Apideck API.
• ALWAYS pass security, app ID, and consumer ID via functional options when creating the client.
• USE ServiceID on requests to specify which downstream connector to use.
• ALWAYS check returned error values (idiomatic Go error handling).
• USE sdkgo.Pointer() helper for optional fields.
• DO NOT store API keys in source code. Use environment variables.

Quick Start

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    sdkgo "github.com/apideck-libraries/sdk-go"
    "github.com/apideck-libraries/sdk-go/models/components"
    "github.com/apideck-libraries/sdk-go/models/operations"
)

func main() {
    ctx := context.Background()

    s := sdkgo.New(
        sdkgo.WithConsumerID("your-consumer-id"),
        sdkgo.WithAppID("your-app-id"),
        sdkgo.WithSecurity(os.Getenv("APIDECK_API_KEY")),
    )

    res, err := s.Crm.Contacts.List(ctx, operations.CrmContactsAllRequest{
        ServiceID: sdkgo.Pointer("salesforce"),
        Limit:     sdkgo.Pointer(int64(20)),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, contact := range res.GetContactsResponse.Data {
        fmt.Println(contact.Name)
    }
}

SDK Patterns

Client Setup

import sdkgo "github.com/apideck-libraries/sdk-go"

s := sdkgo.New(
    sdkgo.WithConsumerID("your-consumer-id"),
    sdkgo.WithAppID("your-app-id"),
    sdkgo.WithSecurity(os.Getenv("APIDECK_API_KEY")),
)

CRUD Operations

All resources follow the pattern: s.{Api}.{Resource}.{Operation}(ctx, request), returning (response, error).

import (
    sdkgo "github.com/apideck-libraries/sdk-go"
    "github.com/apideck-libraries/sdk-go/models/components"
    "github.com/apideck-libraries/sdk-go/models/operations"
)

ctx := context.Background()

// LIST
res, err := s.Crm.Contacts.List(ctx, operations.CrmContactsAllRequest{
    ServiceID: sdkgo.Pointer("salesforce"),
    Limit:     sdkgo.Pointer(int64(20)),
    Filter: &components.ContactsFilter{
        Email: sdkgo.Pointer("[email protected]"),
    },
    Sort: &components.ContactsSort{
        By:        (*components.ContactsSortBy)(sdkgo.Pointer("updated_at")),
        Direction: (*components.SortDirection)(sdkgo.Pointer("desc")),
    },
})

// CREATE
res, err := s.Crm.Contacts.Create(ctx, operations.CrmContactsAddRequest{
    ServiceID: sdkgo.Pointer("salesforce"),
    Contact: components.ContactInput{
        FirstName: sdkgo.Pointer("John"),
        LastName:  sdkgo.Pointer("Doe"),
        Emails: []components.Email{
            {Email: sdkgo.Pointer("[email protected]"), Type: (*components.EmailType)(sdkgo.Pointer("primary"))},
        },
        PhoneNumbers: []components.PhoneNumber{
            {Number: sdkgo.Pointer("+1234567890"), Type: (*components.PhoneNumberType)(sdkgo.Pointer("mobile"))},
        },
    },
})

// GET
res, err := s.Crm.Contacts.Get(ctx, operations.CrmContactsOneRequest{
    ID:        "contact_123",
    ServiceID: sdkgo.Pointer("salesforce"),
})

// UPDATE
res, err := s.Crm.Contacts.Update(ctx, operations.CrmContactsUpdateRequest{
    ID:        "contact_123",
    ServiceID: sdkgo.Pointer("salesforce"),
    Contact: components.ContactInput{
        FirstName: sdkgo.Pointer("Jane"),
    },
})

// DELETE
res, err := s.Crm.Contacts.Delete(ctx, operations.CrmContactsDeleteRequest{
    ID:        "contact_123",
    ServiceID: sdkgo.Pointer("salesforce"),
})

Pagination

Use the Next() method on the response. Returns nil when no more pages:

res, err := s.Accounting.Invoices.List(ctx, operations.AccountingInvoicesAllRequest{
    ServiceID: sdkgo.Pointer("quickbooks"),
    Limit:     sdkgo.Pointer(int64(50)),
})
if err != nil {
    log.Fatal(err)
}

for {
    for _, invoice := range res.GetInvoicesResponse.Data {
        fmt.Printf("%s: %v\n", *invoice.Number, *invoice.Total)
    }

    res, err = res.Next()
    if err != nil {
        log.Fatal(err)
    }
    if res == nil {
        break
    }
}

Error Handling

import (
    "errors"
    "github.com/apideck-libraries/sdk-go/models/apierrors"
)

res, err := s.Crm.Contacts.Get(ctx, req)
if err != nil {
    var badReq *apierrors.BadRequestResponse
    var unauthorized *apierrors.UnauthorizedResponse
    var notFound *apierrors.NotFoundResponse
    var paymentReq *apierrors.PaymentRequiredResponse
    var unprocessable *apierrors.UnprocessableResponse

    switch {
    case errors.As(err, &badReq):
        log.Printf("Bad request: %s", badReq.Error())
    case errors.As(err, &unauthorized):
        log.Printf("Unauthorized: %s", unauthorized.Error())
    case errors.As(err, &notFound):
        log.Printf("Not found: %s", notFound.Error())
    case errors.As(err, &paymentReq):
        log.Printf("Payment required: %s", paymentReq.Error())
    case errors.As(err, &unprocessable):
        log.Printf("Unprocessable: %s", unprocessable.Error())
    default:
        var apiErr *apierrors.APIError
        if errors.As(err, &apiErr) {
            log.Printf("API error %d: %s", apiErr.StatusCode, apiErr.Error())
        } else {
            log.Fatal(err)
        }
    }
}

Retry Configuration

import "github.com/apideck-libraries/sdk-go/retry"

// Global
s := sdkgo.New(
    sdkgo.WithRetryConfig(retry.Config{
        Strategy: "backoff",
        Backoff: &retry.BackoffStrategy{
            InitialInterval: 1,
            MaxInterval:     50,
            Exponent:        1.1,
            MaxElapsedTime:  100,
        },
        RetryConnectionErrors: false,
    }),
    sdkgo.WithConsumerID("your-consumer-id"),
    sdkgo.WithAppID("your-app-id"),
    sdkgo.WithSecurity(os.Getenv("APIDECK_API_KEY")),
)

// Per-operation
res, err := s.Crm.Contacts.List(ctx, req,
    operations.WithRetries(retry.Config{
        Strategy: "backoff",
        Backoff:  &retry.BackoffStrategy{InitialInterval: 1, MaxInterval: 50, Exponent: 1.1, MaxElapsedTime: 100},
    }),
)

API Namespaces

| Namespace | Resources | |-----------|-----------| | s.Accounting.* | Invoices, Bills, Payments, Customers, Suppliers, LedgerAccounts, JournalEntries, TaxRates, CreditNotes, PurchaseOrders, BalanceSheet, ProfitAndLoss, and more | | s.Crm.* | Contacts, Companies, Leads, Opportunities, Activities, Notes, Pipelines, Users | | s.Hris.* | Employees, Companies, Departments, Payrolls, TimeOffRequests | | s.FileStorage.* | Files, Folders, Drives, DriveGroups, SharedLinks, UploadSessions | | s.Ats.* | Applicants, Applications, Jobs | | s.Vault.* | Connections, Consumers, Sessions, CustomMappings, Logs | | s.Webhook.* | Webhooks, EventLogs |