GoLang client library & SDK for Payload CMS
Go Payload is a GoLang client library for Payload CMS. It provides a simple and easy-to-use interface for interacting with the Payload CMS API by saving you the hassle of dealing with unmarshalling JSON responses into your Payload collections and globals.
go get -u github.com/ainsleyclark/go-payloadcms
import (
"github.com/ainsleyclark/go-payloadcms"
)
type Entity struct {
ID int `json:"id"`
Email string `json:"email"`
Name string `json:"name"`
// ... other fields
}
func main() {
client, err := payloadcms.New(
payloadcms.WithBaseURL("http://localhost:8080"),
payloadcms.WithAPIKey("api-key"),
)
if err != nil {
log.Fatalln(err)
}
var entities payloadcms.ListResponse[Entity]
resp, err := client.Collections.List(context.Background(), "users", payloadcms.ListParams{}, &entities)
if err != nil {
log.Fatalln(err)
}
fmt.Printf("Received status: %d, with body: %s\n", resp.StatusCode, string(resp.Content))
}
Documentation can be found at the Go Docs, but we have included a kick-start guide below to get you started.
The client provides the services as defined below. Each
Collections
Globals
Media
The collections service provides methods to interact with the collections in Payload CMS. For more information please visit the docs here.
var entity Entity // Any struct that conforms to your collection schema.
resp, err := client.Collections.FindByID(context.Background(), "collection", 1, &entity)
if err != nil {
fmt.Println(err)
return
}
var entities payloadcms.ListResponse[Entity] // Must use ListResponse with generic type.
resp, err := client.Collections.List(context.Background(), "collection", payloadcms.ListParams{
Sort: "-createdAt",
Limit: 10,
Page: 1,
}, entities)
if err != nil {
fmt.Println(err)
return
}
var entity Entity // Any struct representing the entity to be created.
resp, err := client.Collections.Create(context.Background(), "collection", entity)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(resp.Content)) // Can unmarshal into response struct if needed.
var entity Entity // Any struct representing the updated entity.
resp, err := client.Collections.UpdateByID(context.Background(), "collection", 1, entity)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(resp.Content)) // Can unmarshal into response struct if needed.
resp, err := client.Collections.DeleteByID(context.Background(), "collection", 1)
if err != nil {
fmt.Println(err)
return
}
// Use response data as needed
The globals service provides methods to interact with the globals in Payload CMS. For more information please visit the docs here.
var global Global // Any struct representing a global type.
resp, err := client.Globals.Get(context.Background(), "global", &global)
if err != nil {
fmt.Println(err)
return
}
var global Global // Any struct representing a global type.
resp, err := client.Globals.Update(context.Background(), "global", global)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(resp.Content)) // Can unmarshal into response struct if needed.
The media service provides methods to upload media types to Payload CMS. For more information please visit the docs here.
file, err := os.Open("path/to/file")
if err != nil {
fmt.Println(err)
return
}
media := &payloadcms.CreateResponse[Media]{}
_, err = m.payload.Media.UploadFromURL(ctx, file, Media{Alt: "alt"}, &media, payloadcms.MediaOptions{
Collection: "media",
})
if err != nil {
fmt.Println(err)
return
}
media := &payloadcms.CreateResponse[Media]{}
_, err = m.payload.Media.UploadFromURL(ctx, "https://payloadcms.com/picture-of-cat.jpg", Media{Alt: "alt"}, &media, payloadcms.MediaOptions{
Collection: "media",
})
if err != nil {
fmt.Println(err)
return
}
Mock implementations can be found in payloadfakes
package located
in fakes directory.
They provide mock implementations of all the services provided by the client for convenience.
Example:
func TestPayload(t *testing.T) {
// Create a new mock collection service
mockCollectionService := payloadfakes.NewMockCollectionService()
// Define the behavior of the FindByID method
mockCollectionService.FindByIDFunc = func (ctx context.Context,
collection payloadcms.Collection,
id int,
out any,
) (payloadcms.Response, error) {
// Custom logic for the mock implementation
return payloadcms.Response{}, nil
}
// Use the mock collection service in your tests
myFunctionUsingCollectionService(mockCollectionService)
}
The library defines custom response and error types to provide a more convenient way to interact with the API.
- Response: This struct wraps the standard
http.Response
returned by the API and provides additional fields for easier access to response data and potential errors.Content
: The response body bytes.Message
: A user-friendly message extracted from the response (if available).Errors
: A list ofError
structs containing details about any API errors encountered.
- Error: This struct represents a single API error with a
Message
field containing the error description.
These types are used throughout the library to handle successful responses and API errors consistently.
To get set up with Go Payload simply clone the repo and run the following:
make setup
This will install all dependencies and set up the project for development.
Within the ./dev
directory, you will find a local instance of Payload CMS that can be used for
testing the client.
To get setup with Payload, simply follow the steps below.
Copy the environment file and replace where necessary. The postgres-db
adapater is currently being
used for the database.
cp .env.example .env
Then run the Payload instance like you would any other installation.
pnpm run dev
- Auth - https://payloadcms.com/docs/rest-api/overview#auth-operations
- Preferences: https://payloadcms.com/docs/rest-api/overview#preferences
- Finish E2E Tests under
/tests
directory usingdockertest
Contributions are welcome! If you find any bugs or have suggestions for improvement, please open an issue or submit a pull request.
This project is licensed under the MIT License - see the LICENSE file for details.
ainsley.dev and the ainsley.dev logo are either registered trademarks or trademarks of ainsley.dev LTD in the United Kingdom and/or other countries. All other trademarks are the property of their respective owners.