Documentation
¶
Overview ¶
Package amclient provides a Go client for the Archivematica Dashboard API.
A Client exposes services for transfers, ingests, processing configurations, packages, jobs, and tasks. Each service operation returns a Response that wraps the underlying HTTP response.
Archivematica 1.11 and newer identify the pipeline and Dashboard version in API response headers. The pipeline identifier is shared by Dashboard, MCPServer, MCPClient, and other Archivematica subsystems. Use Client.ServerInfo to retrieve this information explicitly, or Response.ServerInfo to extract it from an operation that has already completed. Version provides component access and comparison helpers for clients that need to gate behavior on an Archivematica release.
Index ¶
- Variables
- func CheckResponse(r *http.Response) error
- type Client
- func (c *Client) Do(ctx context.Context, req *http.Request, v interface{}) (*Response, error)
- func (c *Client) NewRequest(ctx context.Context, method, urlStr string, body interface{}, ...) (*http.Request, error)
- func (c *Client) NewRequestJSON(ctx context.Context, method, urlStr string, body interface{}, ...) (*http.Request, error)
- func (c *Client) ServerInfo(ctx context.Context) (*ServerInfo, *Response, error)
- type ClientOpt
- type ErrorResponse
- type IngestHideResponse
- type IngestService
- type IngestServiceOp
- type IngestStatusResponse
- type Job
- type JobStatus
- type JobsListRequest
- type JobsService
- type JobsServiceOp
- type PackageCreateRequest
- type PackageCreateResponse
- type PackageService
- type PackageServiceOp
- type ProcessingConfig
- type ProcessingConfigOp
- type ProcessingConfigService
- type RequestOpt
- type Response
- type ServerInfo
- type Task
- type TaskDateTime
- type TaskDuration
- type TaskService
- type TaskServiceOp
- type TransferApproveRequest
- type TransferApproveResponse
- type TransferHideResponse
- type TransferService
- type TransferServiceOp
- func (s *TransferServiceOp) Approve(ctx context.Context, r *TransferApproveRequest) (*TransferApproveResponse, *Response, error)
- func (s *TransferServiceOp) Hide(ctx context.Context, ID string) (*TransferHideResponse, *Response, error)
- func (s *TransferServiceOp) Start(ctx context.Context, r *TransferStartRequest) (*TransferStartResponse, *Response, error)
- func (s *TransferServiceOp) Status(ctx context.Context, ID string) (*TransferStatusResponse, *Response, error)
- func (s *TransferServiceOp) Unapproved(ctx context.Context, r *TransferUnapprovedRequest) (*TransferUnapprovedResponse, *Response, error)
- type TransferStartRequest
- type TransferStartResponse
- type TransferStatusResponse
- type TransferUnapprovedRequest
- type TransferUnapprovedResponse
- type TransferUnapprovedResponseResult
- type Version
Examples ¶
Constants ¶
This section is empty.
Variables ¶
ErrServerInfoUnavailable indicates that an Archivematica response does not include the server version header. Use errors.Is to test for this error.
Functions ¶
func CheckResponse ¶
CheckResponse checks the API response for errors, and returns them if present. A response is considered an error if it has a status code outside the 200 range. API error responses are expected to have either no response body, or a JSON response body that maps to ErrorResponse. Any other response body will be silently ignored.
Types ¶
type Client ¶
type Client struct {
// Base URL for API requests.
BaseURL *url.URL
// User agent for client
UserAgent string
// Authentication
User string
Key string
// Services used for communicating with the API
Transfer TransferService
Ingest IngestService
ProcessingConfig ProcessingConfigService
Package PackageService
Jobs JobsService
Task TaskService
// contains filtered or unexported fields
}
Client manages communication with Archivematica API.
func (*Client) Do ¶
Do sends an API request and returns the API response. The API response is JSON decoded and stored in the value pointed to by v, or returned as an error if an API error has occurred. If v implements the io.Writer interface, the raw response will be written to v, without attempting to decode it.
func (*Client) NewRequest ¶
func (c *Client) NewRequest(ctx context.Context, method, urlStr string, body interface{}, opts ...RequestOpt) (*http.Request, error)
NewRequest creates an API request. A relative URL can be provided in urlStr, which will be resolved to the BaseURL of the Client. Relative URLS should always be specified without a preceding slash. If specified, the value pointed to by body is form encoded and included in as the request body.
func (*Client) NewRequestJSON ¶
func (c *Client) NewRequestJSON(ctx context.Context, method, urlStr string, body interface{}, opts ...RequestOpt) (*http.Request, error)
NewRequestJSON is similar to NewRequest but encodes the value to JSON.
func (*Client) ServerInfo ¶ added in v0.5.0
ServerInfo retrieves information about the Archivematica Dashboard server. Each call makes an authenticated, non-mutating GET request; results are not cached.
Archivematica's package endpoint returns 501 Not Implemented for GET while including server information in its response headers. ServerInfo treats that expected status as successful when the headers are valid. In that case the returned Response retains its 501 status and err is nil.
Example ¶
Server information can be retrieved explicitly when no other API response is available.
package main
import (
"context"
"fmt"
"log"
"net/http"
"go.artefactual.dev/amclient"
)
func main() {
client := amclient.NewClient(
http.DefaultClient,
"https://archivematica.example.com/",
"api-user",
"api-key",
)
info, _, err := client.ServerInfo(context.Background())
if err != nil {
log.Fatal(err)
}
if info.Version.AtLeast(1, 19, 0) {
fmt.Println("Archivematica supports idempotent package creation")
}
}
Output:
type ClientOpt ¶
ClientOpt are options for New.
func SetUserAgent ¶
SetUserAgent is a client option for setting the user agent.
type ErrorResponse ¶
An ErrorResponse reports the error caused by an API request
func (*ErrorResponse) Error ¶
func (r *ErrorResponse) Error() string
type IngestHideResponse ¶
type IngestHideResponse struct {
Removed bool `json:"removed"`
}
type IngestService ¶
type IngestService interface {
Status(context.Context, string) (*IngestStatusResponse, *Response, error)
Hide(context.Context, string) (*IngestHideResponse, *Response, error)
}
Ingest is an interface for interfacing with the Ingest endpoints of the Dashboard API.
type IngestServiceOp ¶
type IngestServiceOp struct {
// contains filtered or unexported fields
}
IngestServiceOp handles communication with the Ingest related methods of the Archivematica API.
func (*IngestServiceOp) Hide ¶
func (s *IngestServiceOp) Hide(ctx context.Context, ID string) (*IngestHideResponse, *Response, error)
func (*IngestServiceOp) Status ¶
func (s *IngestServiceOp) Status(ctx context.Context, ID string) (*IngestStatusResponse, *Response, error)
type IngestStatusResponse ¶
type IngestStatusResponse struct {
ID string `json:"uuid"`
Status string `json:"status"`
Name string `json:"name"`
SIPID string `json:"sip_uuid"`
Microservice string `json:"microservice"`
Directory string `json:"directory"`
Path string `json:"path"`
Message string `json:"message"`
Type string `json:"type"`
}
type JobStatus ¶
type JobStatus int
func (JobStatus) MarshalJSON ¶
MarshalJSON marshals the enum as a quoted json string
func (*JobStatus) UnmarshalJSON ¶
UnmarshalJSON unmashals a quoted json string to the enum value
type JobsListRequest ¶
type JobsListRequest struct {
Microservice string `json:"microservice,omitempty"`
LinkID string `json:"link_uuid,omitempty"`
Name string `json:"name,omitempty"`
// Detailed instructs the server to return additional data in the response.
// This feature is available starting from Archivematica 1.16, which was not
// released at the time this comment was written.
Detailed bool `json:"-"`
}
type JobsService ¶
type JobsServiceOp ¶
type JobsServiceOp struct {
// contains filtered or unexported fields
}
func (*JobsServiceOp) List ¶
func (s *JobsServiceOp) List(ctx context.Context, ID string, r *JobsListRequest) ([]Job, *Response, error)
type PackageCreateRequest ¶
type PackageCreateRequest struct {
Name string `json:"name"`
Type string `json:"type"`
Path string `json:"path"`
Accession string `json:"accession,omitempty"`
AccessSystemID string `json:"access_system_id,omitempty"`
MetadataSetID string `json:"metadata_set_id,omitempty"`
ProcessingConfig string `json:"processing_config,omitempty"`
AutoApprove *bool `json:"auto_approve,omitempty"`
IdempotencyKey string `json:"-"`
}
type PackageCreateResponse ¶
type PackageCreateResponse struct {
ID string `json:"id,omitempty"`
}
type PackageService ¶
type PackageService interface {
Create(context.Context, *PackageCreateRequest) (*PackageCreateResponse, *Response, error)
}
type PackageServiceOp ¶
type PackageServiceOp struct {
// contains filtered or unexported fields
}
func (*PackageServiceOp) Create ¶
func (s *PackageServiceOp) Create(ctx context.Context, r *PackageCreateRequest) (*PackageCreateResponse, *Response, error)
type ProcessingConfig ¶
ProcessingConfig represents the processing configuration document returned by the Dashboard API.
type ProcessingConfigOp ¶
type ProcessingConfigOp struct {
// contains filtered or unexported fields
}
ProcessingConfigOp handles communication with the Tranfer related methods of the Archivematica API.
func (*ProcessingConfigOp) Get ¶
func (s *ProcessingConfigOp) Get(ctx context.Context, name string) (*ProcessingConfig, *Response, error)
Get obtains a processing configuration given its name.
type ProcessingConfigService ¶
type ProcessingConfigService interface {
Get(context.Context, string) (*ProcessingConfig, *Response, error)
List(context.Context) ([]string, *Response, error)
}
ProcessingConfigService is an interface for interfacing with the processing configuration endpoints of the Dashboard API.
type RequestOpt ¶
RequestOpt is a function type used to alter requests.
func WithRequestAcceptXML ¶
func WithRequestAcceptXML() RequestOpt
WithRequestAcceptXML sets the Accept header to "application/xml". This is needed when consuming endpoints that require this configuration.
type Response ¶
Response is an Archivematica response. This wraps the standard http.Response returned from Archivematica.
func (*Response) ServerInfo ¶ added in v0.5.0
func (r *Response) ServerInfo() (*ServerInfo, error)
ServerInfo extracts Archivematica server information from response headers. It does not make a network request. It returns ErrServerInfoUnavailable when the version header is absent and an error when the version is malformed.
Example ¶
package main
import (
"context"
"fmt"
"log"
"net/http"
"go.artefactual.dev/amclient"
)
func main() {
client := amclient.NewClient(
http.DefaultClient,
"https://archivematica.example.com/",
"api-user",
"api-key",
)
_, response, err := client.ProcessingConfig.List(context.Background())
if err != nil {
log.Fatal(err)
}
info, err := response.ServerInfo()
if err != nil {
log.Fatal(err)
}
fmt.Printf("Archivematica %s (pipeline %s)\n", info.Version, info.ID)
}
Output:
type ServerInfo ¶ added in v0.5.0
type ServerInfo struct {
// Version is the Archivematica release version.
Version Version
// ID is the pipeline identifier shared by Dashboard, MCPServer, MCPClient,
// and other Archivematica subsystems. It is empty when the server does not
// provide X-Archivematica-ID.
ID string
}
ServerInfo describes the Archivematica server and pipeline that handled an API request.
type Task ¶
type Task struct {
ID string `json:"uuid"`
ExitCode int `json:"exit_code"`
FileID string `json:"file_uuid"`
Filename string `json:"file_name"`
CreatedAt TaskDateTime `json:"time_created"`
StartedAt TaskDateTime `json:"time_started"`
CompletedAt TaskDateTime `json:"time_ended"`
Duration TaskDuration `json:"duration"`
}
type TaskDateTime ¶
func (*TaskDateTime) UnmarshalJSON ¶
func (t *TaskDateTime) UnmarshalJSON(data []byte) error
type TaskDuration ¶ added in v0.3.0
TaskDuration extends the standard time.Duration type to provide specialized unmarshaling from JSON. Unlike time.Duration, which typically requires duration values to be specified in string format (like "300ms", "1h30m"), TaskDuration is designed to unmarshal from two distinct JSON value types:
- Integer values representing the duration in seconds.
- A specific string literal "< 1", which we interpret as half a second.
Examples:
- `{"duration": 60}` unmarshals to 60 seconds,
- `{"duration": "< 1"}` unmarshals to 500 milliseconds.
Python function: https://github.com/artefactual/archivematica/blob/2c03a79e710d655c3740ddbc4bc62eebd4e4b4fe/src/dashboard/src/components/helpers.py#L163-L170.
func (*TaskDuration) UnmarshalJSON ¶ added in v0.3.0
func (d *TaskDuration) UnmarshalJSON(data []byte) error
type TaskService ¶
type TaskServiceOp ¶
type TaskServiceOp struct {
// contains filtered or unexported fields
}
type TransferApproveRequest ¶
type TransferApproveRequest struct {
Type string `schema:"type"`
Directory string `schema:"directory"`
}
TransferApproveRequest represents a request to approve a transfer.
type TransferApproveResponse ¶
TransferApproveResponse represents a response to TransferApproveRequest.
type TransferHideResponse ¶
type TransferHideResponse struct {
Removed bool `json:"removed"`
}
type TransferService ¶
type TransferService interface {
Start(context.Context, *TransferStartRequest) (*TransferStartResponse, *Response, error)
Approve(context.Context, *TransferApproveRequest) (*TransferApproveResponse, *Response, error)
Unapproved(context.Context, *TransferUnapprovedRequest) (*TransferUnapprovedResponse, *Response, error)
Status(context.Context, string) (*TransferStatusResponse, *Response, error)
Hide(context.Context, string) (*TransferHideResponse, *Response, error)
}
TransferService is an interface for interfacing with the Transfer endpoints of the Dashboard API.
type TransferServiceOp ¶
type TransferServiceOp struct {
// contains filtered or unexported fields
}
TransferServiceOp handles communication with the Tranfer related methods of the Archivematica API.
func (*TransferServiceOp) Approve ¶
func (s *TransferServiceOp) Approve(ctx context.Context, r *TransferApproveRequest) (*TransferApproveResponse, *Response, error)
Approve approves an existing transfer awaiting for approval.
func (*TransferServiceOp) Hide ¶
func (s *TransferServiceOp) Hide(ctx context.Context, ID string) (*TransferHideResponse, *Response, error)
func (*TransferServiceOp) Start ¶
func (s *TransferServiceOp) Start(ctx context.Context, r *TransferStartRequest) (*TransferStartResponse, *Response, error)
Start starts a new transfer.
func (*TransferServiceOp) Status ¶
func (s *TransferServiceOp) Status(ctx context.Context, ID string) (*TransferStatusResponse, *Response, error)
func (*TransferServiceOp) Unapproved ¶
func (s *TransferServiceOp) Unapproved(ctx context.Context, r *TransferUnapprovedRequest) (*TransferUnapprovedResponse, *Response, error)
Unapproved lists existing transfers waiting for approval.
type TransferStartRequest ¶
type TransferStartRequest struct {
Name string `schema:"name"`
Type string `schema:"type"`
Paths []string `schema:"paths"`
}
TransferStartRequest represents a request to start a transfer.
type TransferStartResponse ¶
TransferStartResponse represents a response to TransferStartRequest.
type TransferStatusResponse ¶
type TransferStatusResponse struct {
ID string `json:"uuid"`
Status string `json:"status"`
Name string `json:"name"`
SIPID string `json:"sip_uuid"`
Microservice string `json:"microservice"`
Directory string `json:"directory"`
Path string `json:"path"`
Message string `json:"message"`
Type string `json:"type"`
}
func (TransferStatusResponse) SIP ¶
func (t TransferStatusResponse) SIP() (string, bool)
type TransferUnapprovedRequest ¶
type TransferUnapprovedRequest struct{}
TransferUnapprovedRequest represents a request to list unapproved transfer.
type TransferUnapprovedResponse ¶
type TransferUnapprovedResponse struct {
Message string `json:"message"`
Results []*TransferUnapprovedResponseResult `json:"results"`
}
TransferUnapprovedResponse represents a response to TransferUnapprovedRequest.
type TransferUnapprovedResponseResult ¶
type TransferUnapprovedResponseResult struct {
Type string `json:"type"`
Directory string `json:"directory"`
UUID string `json:"uuid"`
}
TransferUnapprovedResponseResult represents a result of TransferUnapprovedResponse.
type Version ¶ added in v0.5.0
type Version struct {
// contains filtered or unexported fields
}
Version is an immutable numeric Archivematica release version parsed from the X-Archivematica-Version response header. Its zero value represents 0.0.0.
func (Version) AtLeast ¶ added in v0.5.0
AtLeast reports whether v is greater than or equal to the version identified by major, minor, and patch. It is intended for release feature checks such as v.AtLeast(1, 19, 0).
func (Version) Compare ¶ added in v0.5.0
Compare compares v with other. It returns -1, 0, or 1 when v is less than, equal to, or greater than other, respectively.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package amclienttest is a generated GoMock package.
|
Package amclienttest is a generated GoMock package. |