Based on customer feedback, we have been working on improving our all-category SDKs. We recently released our New Generation Go SDK. It is currently available for anyone to use.
Note that the existing Go SDKs are fully functional and will continue to work.
There are key benefits in using this new generation SDK. We understand that migrating will take both time and effort, which is why we’ve worked on putting together this helpful migration guide.
We strongly recommend to use the new SDKs. You’ll play an integral role in providing feedback on our SDKs, making them more usable and robust and get a head start on migrating over.
We would love any and all feedback by reaching out to your engagement manager or [email protected]. All your feedback will be promptly addressed.
Migration Guide
This guide is for Merge customers using the merge-<category>-go SDKs:
Generation | SDK Name | Github | Package Name |
0 | HRIS Go | ||
0 | CRM Go | ||
0 | Ticketing Go | ||
0 | Accounting Go |
We recommend all customers move to the Advanced SDK:
Go Package Manager: https://pkg.go.dev/github.com/merge-api/merge-go-client
This SDK has the following advantages:
Feature | Description |
Multi-category SDK | The new Go SDK contains support for all released Merge categories meaning expanding to a new vertical doesn’t require using a second SDK. |
More http layer configurability | Easier configuration options to change timeouts, retries, etc. |
Error handling | Structured error types are returned from API calls that return non-success status codes. For example, you can check if the error was due to a bad request (i.e. status code 400). These errors are also compatible with the |
Tests | This SDK ships with a much more comprehensive set of unit tests compared with the prior SDK. |
This SDK has all Merge categories, which makes it easy for Merge customers to find all endpoint methods in one package. The earlier single-category SDKs all have the same style of method call, so let’s consider what it looks like to move from an existing employees list call to the new SDK.
Go Instantiation
First, you need to run the following command to use the Merge Go library in your Go module
...
go get github.com/stretchr/testify/assert
go get golang.org/x/oauth2
go get golang.org/x/net/context
...
Then put the package under your project folder and add the following import.
import sw "./merge_hris_client"
To bring in the new package, swap out the go get commands with the following:
... go get github.com/merge-api/merge-go-client ...
Then import the new package with the following:
import (
"context"
"fmt"
merge "github.com/merge-api/merge-go-client"
mergeclient "github.com/merge-api/merge-go-client/client"
)
Earlier SDK Code
package main
import (
"context"
"fmt"
"os"
"time"
openapiclient "./openapi"
)
func main() {
xAccountToken := "xAccountToken_example"
companyId := "companyId_example"
createdAfter := time.Now()
createdBefore := time.Now()
cursor := "cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw"
displayFullName := "displayFullName_example"
employmentStatus := "employmentStatus_example"
firstName := "firstName_example"
groups := "groups_example"
includeDeletedData := true
includeRemoteData := true
includeSensitiveFields := true
lastName := "lastName_example"
managerId := "managerId_example"
modifiedAfter := time.Now()
modifiedBefore := time.Now()
pageSize := int32(56)
payGroupId := "payGroupId_example"
personalEmail := "[email protected]"
remoteFields := "employment_status,ethnicity,gender,marital_status"
remoteId := "remoteId_example"
showEnumOrigins := "employment_status,ethnicity,gender,marital_status"
startedAfter := time.Now()
startedBefore := time.Now()
teamId := "teamId_example"
terminatedAfter := time.Now()
terminatedBefore := time.Now()
workEmail := "[email protected]"
workLocationId := "workLocationId_example"
configuration := openapiclient.NewConfiguration()
api_client := openapiclient.NewAPIClient(configuration)
resp, r, err := api_client.EmployeesApi.EmployeesList(context.Background()).XAccountToken(xAccountToken).CompanyId(companyId).CreatedAfter(createdAfter).CreatedBefore(createdBefore).Cursor(cursor).DisplayFullName(displayFullName).EmploymentStatus(employmentStatus).FirstName(firstName).Groups(groups).IncludeDeletedData(includeDeletedData).IncludeRemoteData(includeRemoteData).IncludeSensitiveFields(includeSensitiveFields).LastName(lastName).ManagerId(managerId).ModifiedAfter(modifiedAfter).ModifiedBefore(modifiedBefore).PageSize(pageSize).PayGroupId(payGroupId).PersonalEmail(personalEmail).RemoteFields(remoteFields).RemoteId(remoteId).ShowEnumOrigins(showEnumOrigins).StartedAfter(startedAfter).StartedBefore(startedBefore).TeamId(teamId).TerminatedAfter(terminatedAfter).TerminatedBefore(terminatedBefore).WorkEmail(workEmail).WorkLocationId(workLocationId).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `EmployeesApi.EmployeesList``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
// response from `EmployeesList`: PaginatedEmployeeList
fmt.Fprintf(os.Stdout, "Response from `EmployeesApi.EmployeesList`: %v\n", resp)
}
Advanced SDK Equivalent
import (
"context"
"fmt"
merge "github.com/fern-api/merge-go"
mergeclient "github.com/fern-api/merge-go/client"
"github.com/fern-api/merge-go/hris"
)
client := mergeclient.NewClient(
mergeclient.ClientWithAuthApiKey("<YOUR_API_KEY>"),
mergeclient.ClientWithHeaderAccountToken("<YOUR_ACCOUNT_TOKEN>"),
)
employee, err := client.Hris().Employees().Retrieve(
context.TODO(),
"0958cbc6-6040-430a-848e-aafacbadf4ae",
&hris.EmployeesRetrieveRequest{
IncludeRemoteData: merge.Bool(true),
},
)
if err != nil {
return err
}
fmt.Printf("Retrieved employee with ID %q\n", *employee.Id)Here are some key advantages from the new client class:
Here are some key advantages from the new client class:
Authentication configuration has been somewhat simplified, you do not need to specify
"Bearer"prefix anymore as it is assumed.Pagination is easier, there are helper methods as well as the built-in iterator