Skip to content

README.md

Latest commit

 

History

History
185 lines (143 loc) · 4.51 KB

README.md

File metadata and controls

185 lines (143 loc) · 4.51 KB
Raw

Golang API client for Uploadcare

license GoDoc

Uploadcare Golang API client that handles uploads and further operations with files by wrapping Uploadcare Upload and REST APIs.

Requirements

Go 1.25

Installation

Install uploadcare-go with:

go get -u -v github.com/uploadcare/uploadcare-go/v2/...

Then import it using:

import (
	"github.com/uploadcare/uploadcare-go/v2/ucare"
	"github.com/uploadcare/uploadcare-go/v2/file"
	"github.com/uploadcare/uploadcare-go/v2/group"
	"github.com/uploadcare/uploadcare-go/v2/upload"
	"github.com/uploadcare/uploadcare-go/v2/conversion"
	"github.com/uploadcare/uploadcare-go/v2/projectapi"
)

Configuration

REST & Upload API client

creds := ucare.APICreds{
	SecretKey: "your-project-secret-key",
	PublicKey: "your-project-public-key",
}

conf := &ucare.Config{
	SignBasedAuthentication: true,
}

client, err := ucare.NewClient(creds, conf)
if err != nil {
	log.Fatal("creating uploadcare API client: %s", err)
}

Project API client

The Project API uses bearer token authentication. Tokens can be obtained via Uploadcare Support.

client, err := ucare.NewBearerClient("your-bearer-token", nil)
if err != nil {
	log.Fatal("creating project API client: %s", err)
}

projectSvc := projectapi.NewService(client)

Usage

For a comprehensive list of examples, check out the API documentation. Below are a few usage examples:

Getting a list of files:

fileSvc := file.NewService(client)

listParams := file.ListParams{
	Stored:  ucare.Bool(true),
	OrderBy: ucare.String(file.OrderByUploadedAtDesc),
}

fileList, err := fileSvc.List(context.Background(), listParams)
if err != nil {
	// handle error
}

// getting IDs of the files
ids := make([]string, 0, 100)
for fileList.Next() {
	finfo, err :=  fileList.ReadResult()
	if err != nil {
		// handle error
	}

	ids = append(ids, finfo.ID)
}

Acquiring file-specific info:

fileID := ids[0]
file, err := fileSvc.Info(context.Background(), fileID, nil)
if err != nil {
	// handle error
}

if file.IsImage && file.ContentInfo != nil && file.ContentInfo.Image != nil {
	h := file.ContentInfo.Image.Height
	w := file.ContentInfo.Image.Width
	fmt.Printf("image size: %dx%d\n", h, w)
}

Uploading a file:

f, err := os.Open("file.png")
if err != nil {
	// handle error
}

uploadSvc := upload.NewService(client)

params := upload.FileParams{
	Data:        f,
	Name:        f.Name(),
	ContentType: "image/png",
}
fID, err := uploadSvc.File(context.Background(), params)
if err != nil {
	// handle error
}

Managing projects via the Project API:

client, err := ucare.NewBearerClient("your-bearer-token", nil)
if err != nil {
	// handle error
}

projectSvc := projectapi.NewService(client)

// List all projects
projects, err := projectSvc.List(context.Background(), nil)
if err != nil {
	// handle error
}

// Get project details
proj, err := projectSvc.Get(context.Background(), projects.Results[0].PubKey)
if err != nil {
	// handle error
}
fmt.Printf("project: %s (%s)\n", proj.Name, proj.PubKey)

// Get usage metrics
usage, err := projectSvc.GetUsage(context.Background(), proj.PubKey, projectapi.UsageDateRange{
	From: "2025-01-01",
	To:   "2025-01-31",
})
if err != nil {
	// handle error
}

Useful links

Golang API client documentation
Uploadcare documentation
Upload API reference
REST API reference Changelog
Contributing guide
Security policy
Support