api

Documentation

Overview

Package api provides HTTP client for microCMS APIs with retry and error mapping.

Index

• type APIInfo
• type APIListResponse
• type APISchema
• type Client
  • func NewClient(contentURL, mgmtURL, contentKey, mgmtKey string) *Client
  • func (c *Client) DoContent(ctx context.Context, method, path string, body io.Reader, ...) (*Response, error)
  • func (c *Client) DoManagement(ctx context.Context, method, path string, body io.Reader, ...) (*Response, error)
  • func (c *Client) DownloadFile(ctx context.Context, fileURL string) ([]byte, error)
  • func (c *Client) GetAPISchema(ctx context.Context, endpoint string) (*APISchema, error)
  • func (c *Client) GetContent(ctx context.Context, endpoint string, contentID string) (map[string]any, error)
  • func (c *Client) GetContentMeta(ctx context.Context, endpoint, contentID string) (*ContentMeta, error)
  • func (c *Client) GetMember(ctx context.Context, memberID string) (*MemberInfo, error)
  • func (c *Client) GetServiceInfo(ctx context.Context) (*ServiceInfo, error)
  • func (c *Client) ListAPIs(ctx context.Context) ([]APIInfo, error)
  • func (c *Client) ListAllContents(ctx context.Context, endpoint string, onPage func(fetched, total int)) ([]map[string]any, int, error)
  • func (c *Client) ListAllMedia(ctx context.Context, onPage func(fetched, total int)) ([]MediaInfo, error)
  • func (c *Client) ListContentMeta(ctx context.Context, endpoint string) (*ContentMetaListResponse, error)
  • func (c *Client) ListContents(ctx context.Context, endpoint string, params ListParams) (*ListResponse, error)
  • func (c *Client) ListMedia(ctx context.Context, limit int, token string) (*MediaListResponse, error)
  • func (c *Client) ListMembers(ctx context.Context) ([]MemberInfo, error)
• type ContentMeta
• type ContentMetaListResponse
• type CustomField
• type FieldSchema
• type ListParams
• type ListResponse
• type MediaInfo
• type MediaListResponse
• type MemberInfo
• type MemberListResponse
• type Response
  • func (r *Response) JSON(v any) error
• type RetryConfig
  • func DefaultRetryConfig() RetryConfig
• type ServiceInfo

Types

type APIInfo

type APIInfo struct {
	APIID   string `json:"endpoint"`
	APIName string `json:"name"`
	APIType string `json:"type"` // "list" or "object"
}

APIInfo represents a single API endpoint.

type APIListResponse

type APIListResponse struct {
	APIs []APIInfo `json:"apis"`
}

APIListResponse is the response for listing APIs.

type APISchema

type APISchema struct {
	APIFields    []FieldSchema `json:"apiFields"`
	CustomFields []CustomField `json:"customFields,omitempty"`
}

APISchema represents the schema of an API endpoint.

type Client

type Client struct {
	HTTPClient  *http.Client
	ContentURL  string
	MgmtURL     string
	ContentKey  string
	MgmtKey     string
	Timeout     time.Duration
	RetryConfig RetryConfig
	Debug       bool
	DebugWriter io.Writer
}

Client is an HTTP client for microCMS APIs.

func NewClient

func NewClient(contentURL, mgmtURL, contentKey, mgmtKey string) *Client

NewClient creates a new API client.

func (*Client) DoContent

func (c *Client) DoContent(ctx context.Context, method, path string, body io.Reader, query map[string]string) (*Response, error)

DoContent makes a request to the content API.

func (*Client) DoManagement

func (c *Client) DoManagement(ctx context.Context, method, path string, body io.Reader, query map[string]string) (*Response, error)

DoManagement makes a request to the management API.

func (*Client) DownloadFile

func (c *Client) DownloadFile(ctx context.Context, fileURL string) ([]byte, error)

DownloadFile downloads a file from a URL and returns the body bytes. Media assets on microcms-assets.io are public and don't require an API key.

func (*Client) GetAPISchema

func (c *Client) GetAPISchema(ctx context.Context, endpoint string) (*APISchema, error)

GetAPISchema retrieves the schema for an API endpoint.

func (*Client) GetContent

func (c *Client) GetContent(ctx context.Context, endpoint string, contentID string) (map[string]any, error)

GetContent retrieves a single content by ID, or an object-type endpoint.

func (*Client) GetContentMeta

func (c *Client) GetContentMeta(ctx context.Context, endpoint, contentID string) (*ContentMeta, error)

GetContentMeta retrieves content metadata for a specific content.

func (*Client) GetMember

func (c *Client) GetMember(ctx context.Context, memberID string) (*MemberInfo, error)

GetMember retrieves a specific member.

func (*Client) GetServiceInfo

func (c *Client) GetServiceInfo(ctx context.Context) (*ServiceInfo, error)

GetServiceInfo retrieves service information.

func (*Client) ListAPIs

func (c *Client) ListAPIs(ctx context.Context) ([]APIInfo, error)

ListAPIs retrieves the list of APIs.

func (*Client) ListAllContents

func (c *Client) ListAllContents(ctx context.Context, endpoint string, onPage func(fetched, total int)) ([]map[string]any, int, error)

ListAllContents retrieves all contents by paginating through all pages.

func (*Client) ListAllMedia

func (c *Client) ListAllMedia(ctx context.Context, onPage func(fetched, total int)) ([]MediaInfo, error)

ListAllMedia retrieves all media items by paginating with tokens.

func (*Client) ListContentMeta

func (c *Client) ListContentMeta(ctx context.Context, endpoint string) (*ContentMetaListResponse, error)

ListContentMeta retrieves content metadata list for an endpoint.

func (*Client) ListContents

func (c *Client) ListContents(ctx context.Context, endpoint string, params ListParams) (*ListResponse, error)

ListContents retrieves a list of contents from an endpoint.

func (*Client) ListMedia

func (c *Client) ListMedia(ctx context.Context, limit int, token string) (*MediaListResponse, error)

ListMedia retrieves a page of media items using v2 API.

func (*Client) ListMembers

func (c *Client) ListMembers(ctx context.Context) ([]MemberInfo, error)

ListMembers retrieves the list of team members.

type ContentMeta

type ContentMeta struct {
	ContentID    string `json:"contentId"`
	CreatedAt    string `json:"createdAt"`
	UpdatedAt    string `json:"updatedAt"`
	PublishedAt  string `json:"publishedAt,omitempty"`
	RevisedAt    string `json:"revisedAt,omitempty"`
	Status       string `json:"status"`
	DraftKey     string `json:"draftKey,omitempty"`
	PublishValue any    `json:"publishValue,omitempty"`
	DraftValue   any    `json:"draftValue,omitempty"`
}

ContentMeta represents content metadata from management API.

type ContentMetaListResponse

type ContentMetaListResponse struct {
	Contents   []ContentMeta `json:"contents"`
	TotalCount int           `json:"totalCount"`
	Offset     int           `json:"offset"`
	Limit      int           `json:"limit"`
}

ContentMetaListResponse is the response for listing content metadata.

type CustomField

type CustomField struct {
	CreatedAt string        `json:"createdAt,omitempty"`
	FieldID   string        `json:"fieldId"`
	Name      string        `json:"name"`
	Fields    []FieldSchema `json:"fields"`
	UpdatedAt string        `json:"updatedAt,omitempty"`
}

CustomField represents a custom field definition.

type FieldSchema

type FieldSchema struct {
	FieldID     string `json:"fieldId"`
	Name        string `json:"name"`
	Kind        string `json:"kind"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required"`
	IsUnique    bool   `json:"isUnique"`
}

FieldSchema represents a field in an API schema.

type ListParams

type ListParams struct {
	Limit   int
	Offset  int
	Fields  string
	Orders  string
	Filters string
}

ListParams holds parameters for listing contents.

type ListResponse

type ListResponse struct {
	Contents   []map[string]any `json:"contents"`
	TotalCount int              `json:"totalCount"`
	Offset     int              `json:"offset"`
	Limit      int              `json:"limit"`
}

ListResponse represents a list API response.

type MediaInfo

type MediaInfo struct {
	ID        string   `json:"id"`
	URL       string   `json:"url"`
	Width     int      `json:"width,omitempty"`
	Height    int      `json:"height,omitempty"`
	Tags      []string `json:"tags,omitempty"`
	Alt       string   `json:"alt,omitempty"`
	CreatedAt string   `json:"createdAt"`
	UpdatedAt string   `json:"updatedAt"`
}

MediaInfo represents a media item (v2 API).

type MediaListResponse

type MediaListResponse struct {
	Media      []MediaInfo `json:"media"`
	TotalCount int         `json:"totalCount"`
	Token      string      `json:"token,omitempty"`
}

MediaListResponse is the response for listing media (v2 API).

type MemberInfo

type MemberInfo struct {
	MemberID string `json:"memberId"`
	Name     string `json:"name"`
	Email    string `json:"email"`
	Role     string `json:"role"`
}

MemberInfo represents a team member.

type MemberListResponse

type MemberListResponse struct {
	Contents []MemberInfo `json:"contents"`
}

MemberListResponse is the response for listing members.

type Response

type Response struct {
	StatusCode int
	Body       []byte
}

Response wraps an HTTP response body.

func (*Response) JSON

func (r *Response) JSON(v any) error

JSON unmarshals the response body into v.

type RetryConfig

type RetryConfig struct {
	Enabled      bool
	MaxAttempts  int
	BaseInterval time.Duration
	MaxInterval  time.Duration
	Jitter       bool
	RetryOn      []int
}

RetryConfig configures retry behavior.

func DefaultRetryConfig

func DefaultRetryConfig() RetryConfig

DefaultRetryConfig returns sensible retry defaults.

type ServiceInfo

type ServiceInfo struct {
	Name string `json:"name"`
}

ServiceInfo represents microCMS service information.