jamfpro

Documentation

Overview

jamfpro_api_handler.go

------------------------------Summary----------------------------------------

This is a api handler module for the http_client to accommodate specifics of jamf's api(s). It handles the encoding (marshalling) and decoding (unmarshalling) of data. It also sets the correct content headers for the various http methods.

This module integrates with the http_client logger for wrapped error handling for human readable return codes. It also supports the http_client tiered logging functionality for logging support.

The logic of this module is defined as follows: Classic API:

For requests (GET, POST, PUT, DELETE): - Encoding (Marshalling): Use XML format. For responses (GET, POST, PUT): - Decoding (Unmarshalling): Use XML format. For responses (DELETE): - Handle response codes as response body lacks anything useful. Headers - Sets accept headers based on weighting. XML out weighs JSON to ensure XML is returned - Sets content header as application/xml with edge case exceptions based on need.

JamfPro API:

For requests (GET, POST, PUT, DELETE): - Encoding (Marshalling): Use JSON format. For responses (GET, POST, PUT): - Decoding (Unmarshalling): Use JSON format. For responses (DELETE): - Handle response codes as response body lacks anything useful. Headers - Sets accept headers based on weighting. Jamf Pro API doesn't support XML, so MIME type is skipped and returns JSON - Set content header as application/json with edge case exceptions based on need.

Index

• Constants
• func ExtractErrorMessageFromHTML(htmlContent string) string
• func ParseJSONErrorResponse(body []byte) (string, error)
• type ConfigMap
• type EndpointConfig
• type JamfAPIHandler
  • func (j *JamfAPIHandler) ConstructAPIAuthEndpoint(instanceName string, endpointPath string, log logger.Logger) string
  • func (j *JamfAPIHandler) ConstructAPIResourceEndpoint(instanceName string, endpointPath string, log logger.Logger) string
  • func (j *JamfAPIHandler) GetAPIBearerTokenAuthenticationSupportStatus() bool
  • func (j *JamfAPIHandler) GetAPIOAuthAuthenticationSupportStatus() bool
  • func (j *JamfAPIHandler) GetAPIOAuthWithCertAuthenticationSupportStatus() bool
  • func (u *JamfAPIHandler) GetAcceptHeader() string
  • func (j *JamfAPIHandler) GetBearerTokenEndpoint() string
  • func (u *JamfAPIHandler) GetContentTypeHeader(endpoint string, log logger.Logger) string
  • func (j *JamfAPIHandler) GetDefaultBaseDomain() string
  • func (j *JamfAPIHandler) GetOAuthTokenEndpoint() string
  • func (j *JamfAPIHandler) GetTokenInvalidateEndpoint() string
  • func (j *JamfAPIHandler) GetTokenRefreshEndpoint() string
  • func (u *JamfAPIHandler) MarshalMultipartRequest(fields map[string]string, files map[string]string, log logger.Logger) ([]byte, string, error)
  • func (u *JamfAPIHandler) MarshalRequest(body interface{}, method string, endpoint string, log logger.Logger) ([]byte, error)
  • func (j *JamfAPIHandler) SetBaseDomain() string
  • func (u *JamfAPIHandler) UnmarshalResponse(resp *http.Response, out interface{}, log logger.Logger) error
• type Logger

Constants

const (
	APIName                            = "jamf pro"                      // APIName: represents the name of the API.
	DefaultBaseDomain                  = ".jamfcloud.com"                // DefaultBaseDomain: represents the base domain for the jamf instance.
	OAuthTokenEndpoint                 = "/api/oauth/token"              // OAuthTokenEndpoint: The endpoint to obtain an OAuth token.
	BearerTokenEndpoint                = "/api/v1/auth/token"            // BearerTokenEndpoint: The endpoint to obtain a bearer token.
	TokenRefreshEndpoint               = "/api/v1/auth/keep-alive"       // TokenRefreshEndpoint: The endpoint to refresh an existing token.
	TokenInvalidateEndpoint            = "/api/v1/auth/invalidate-token" // TokenInvalidateEndpoint: The endpoint to invalidate an active token.
	BearerTokenAuthenticationSupport   = true                            // BearerTokenAuthSuppport: A boolean to indicate if the API supports bearer token authentication.
	OAuthAuthenticationSupport         = true                            // OAuthAuthSuppport: A boolean to indicate if the API supports OAuth authentication.
	OAuthWithCertAuthenticationSupport = false                           // OAuthWithCertAuthSuppport: A boolean to indicate if the API supports OAuth with client certificate authentication.
)

Endpoint constants represent the URL suffixes used for Jamf API token interactions.

Functions

func ExtractErrorMessageFromHTML

func ExtractErrorMessageFromHTML(htmlContent string) string

ExtractErrorMessageFromHTML attempts to parse an HTML error page and extract a human-readable error message.

func ParseJSONErrorResponse

func ParseJSONErrorResponse(body []byte) (string, error)

ParseJSONErrorResponse parses the JSON error message from the response body.

Types

type ConfigMap

type ConfigMap map[string]EndpointConfig

ConfigMap is a map that associates endpoint URL patterns with their corresponding configurations. The map's keys are strings that identify the endpoint, and the values are EndpointConfig structs that hold the configuration for that endpoint.

type EndpointConfig

type EndpointConfig struct {
	Accept      string  `json:"accept"`       // Accept specifies the MIME type the endpoint can handle in responses.
	ContentType *string `json:"content_type"` // ContentType, if not nil, specifies the MIME type to set for requests sent to the endpoint. A pointer is used to distinguish between a missing field and an empty string.
}

EndpointConfig is a struct that holds configuration details for a specific API endpoint. It includes what type of content it can accept and what content type it should send.

type JamfAPIHandler

type JamfAPIHandler struct {
	OverrideBaseDomain string // OverrideBaseDomain is used to override the base domain for URL construction.
	InstanceName       string // InstanceName is the name of the Jamf instance.
}

JamfAPIHandler implements the APIHandler interface for the Jamf Pro API.

func (*JamfAPIHandler) ConstructAPIAuthEndpoint

func (j *JamfAPIHandler) ConstructAPIAuthEndpoint(instanceName string, endpointPath string, log logger.Logger) string

ConstructAPIAuthEndpoint constructs the full URL for a Jamf API auth endpoint path and logs the URL.

func (*JamfAPIHandler) ConstructAPIResourceEndpoint

func (j *JamfAPIHandler) ConstructAPIResourceEndpoint(instanceName string, endpointPath string, log logger.Logger) string

ConstructAPIResourceEndpoint constructs the full URL for a Jamf API resource endpoint path and logs the URL.

func (*JamfAPIHandler) GetAPIBearerTokenAuthenticationSupportStatus

func (j *JamfAPIHandler) GetAPIBearerTokenAuthenticationSupportStatus() bool

GetAPIBearerTokenAuthenticationSupportStatus returns a boolean indicating if bearer token authentication is supported in the api handler.

func (*JamfAPIHandler) GetAPIOAuthAuthenticationSupportStatus

func (j *JamfAPIHandler) GetAPIOAuthAuthenticationSupportStatus() bool

GetAPIOAuthAuthenticationSupportStatus returns a boolean indicating if OAuth authentication is supported in the api handler.

func (*JamfAPIHandler) GetAPIOAuthWithCertAuthenticationSupportStatus

func (j *JamfAPIHandler) GetAPIOAuthWithCertAuthenticationSupportStatus() bool

GetAPIOAuthWithCertAuthenticationSupportStatus returns a boolean indicating if OAuth with client certificate authentication is supported in the api handler.

func (*JamfAPIHandler) GetAcceptHeader

func (u *JamfAPIHandler) GetAcceptHeader() string

GetAcceptHeader constructs and returns a weighted Accept header string for HTTP requests. The Accept header indicates the MIME types that the client can process and prioritizes them based on the quality factor (q) parameter. Higher q-values signal greater preference. This function specifies a range of MIME types with their respective weights, ensuring that the server is informed of the client's versatile content handling capabilities while indicating a preference for XML. The specified MIME types cover common content formats like images, JSON, XML, HTML, plain text, and certificates, with a fallback option for all other types.

func (*JamfAPIHandler) GetBearerTokenEndpoint

func (j *JamfAPIHandler) GetBearerTokenEndpoint() string

GetBearerTokenEndpoint returns the endpoint for obtaining a bearer token. Used for constructing API URLs.

func (*JamfAPIHandler) GetContentTypeHeader

func (u *JamfAPIHandler) GetContentTypeHeader(endpoint string, log logger.Logger) string

GetContentTypeHeader determines the appropriate Content-Type header for a given API endpoint. It attempts to find a content type that matches the endpoint prefix in the global configMap. If a match is found and the content type is defined (not nil), it returns the specified content type. If the content type is nil or no match is found in configMap, it falls back to default behaviors: - For url endpoints starting with "/JSSResource", it defaults to "application/xml" for the Classic API. - For url endpoints starting with "/api", it defaults to "application/json" for the JamfPro API. If the endpoint does not match any of the predefined patterns, "application/json" is used as a fallback. This method logs the decision process at various stages for debugging purposes.

func (*JamfAPIHandler) GetDefaultBaseDomain

func (j *JamfAPIHandler) GetDefaultBaseDomain() string

GetDefaultBaseDomain returns the default base domain used for constructing API URLs.

func (*JamfAPIHandler) GetOAuthTokenEndpoint

func (j *JamfAPIHandler) GetOAuthTokenEndpoint() string

GetOAuthTokenEndpoint returns the endpoint for obtaining an OAuth token. Used for constructing API URLs.

func (*JamfAPIHandler) GetTokenInvalidateEndpoint

func (j *JamfAPIHandler) GetTokenInvalidateEndpoint() string

GetTokenInvalidateEndpoint returns the endpoint for invalidating an active token. Used for constructing API URLs.

func (*JamfAPIHandler) GetTokenRefreshEndpoint

func (j *JamfAPIHandler) GetTokenRefreshEndpoint() string

GetTokenRefreshEndpoint returns the endpoint for refreshing an existing token. Used for constructing API URLs.

func (*JamfAPIHandler) MarshalMultipartRequest

func (u *JamfAPIHandler) MarshalMultipartRequest(fields map[string]string, files map[string]string, log logger.Logger) ([]byte, string, error)

MarshalMultipartFormData takes a map with form fields and file paths and returns the encoded body and content type.

func (*JamfAPIHandler) MarshalRequest

func (u *JamfAPIHandler) MarshalRequest(body interface{}, method string, endpoint string, log logger.Logger) ([]byte, error)

MarshalRequest encodes the request body according to the endpoint for the API.

func (*JamfAPIHandler) SetBaseDomain

func (j *JamfAPIHandler) SetBaseDomain() string

SetBaseDomain returns the appropriate base domain for URL construction. It uses j.OverrideBaseDomain if set, otherwise falls back to DefaultBaseDomain.

func (*JamfAPIHandler) UnmarshalResponse

func (u *JamfAPIHandler) UnmarshalResponse(resp *http.Response, out interface{}, log logger.Logger) error

UnmarshalResponse decodes the response body from XML or JSON format depending on the Content-Type header.

type Logger

type Logger interface {
	Debug(msg string, keysAndValues ...interface{})
	Info(msg string, keysAndValues ...interface{})
	Warn(msg string, keysAndValues ...interface{})
	Error(msg string, keysAndValues ...interface{})
}