graph

Documentation

Overview

graph_api_handler.go

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

This is a api handler module for the http_client to accommodate specifics of microsoft's graph 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: Graph API & Graph Beta 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.Graph 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 LoadUserConfig(filename string) error
• type ConfigMap
• type EndpointConfig
• type GraphAPIHandler
  • func (g *GraphAPIHandler) ConstructMSGraphAPIEndpoint(endpointPath string) string
  • func (u *GraphAPIHandler) FetchSupportedRequestFormats(endpoint string) ([]string, error)
  • func (u *GraphAPIHandler) GetAcceptHeader() string
  • func (u *GraphAPIHandler) GetContentTypeHeader(endpoint string) string
  • func (u *GraphAPIHandler) MarshalMultipartRequest(fields map[string]string, files map[string]string) ([]byte, string, error)
  • func (u *GraphAPIHandler) MarshalRequest(body interface{}, method string, endpoint string) ([]byte, error)
  • func (u *GraphAPIHandler) SetLogger(logger Logger)
  • func (u *GraphAPIHandler) UnmarshalResponse(resp *http.Response, out interface{}) error

Constants

const (
	DefaultBaseDomain       = "graph.microsoft.com"           // DefaultBaseDomain: represents the base domain for graph.
	TokenInvalidateEndpoint = "/api/v1/auth/invalidate-token" // TokenInvalidateEndpoint: The endpoint to invalidate an active token.
)

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

Functions

func LoadUserConfig

func LoadUserConfig(filename string) error

LoadUserConfig allows users to apply their own configuration by providing a JSON file. The custom configuration will override the default settings previously loaded. It reads the file from the provided filename path and unmarshals its content into the configMap. If reading or unmarshalling fails, an error is returned.

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 GraphAPIHandler

type GraphAPIHandler struct {
	// contains filtered or unexported fields
}

UnifiedAPIHandler is a struct that implements the APIHandler interface. It holds a Logger instance to facilitate logging across various API handling methods. This handler is responsible for encoding and decoding request and response data, determining content types, and other API interactions as defined by the APIHandler interface.

func (*GraphAPIHandler) ConstructMSGraphAPIEndpoint

func (g *GraphAPIHandler) ConstructMSGraphAPIEndpoint(endpointPath string) string

ConstructMSGraphAPIEndpoint constructs the full URL for an MS Graph API endpoint. The function takes version (e.g., "/v1.0" or "/beta") and the specific API path.

func (*GraphAPIHandler) FetchSupportedRequestFormats

func (u *GraphAPIHandler) FetchSupportedRequestFormats(endpoint string) ([]string, error)

FetchSupportedRequestFormats sends an OPTIONS request to the specified API endpoint and parses the response to extract the MIME types that the endpoint can accept for requests. This function is useful for dynamically determining the supported formats (like JSON, XML, etc.) for an endpoint, which can then be used to set the appropriate 'Content-Type' header in subsequent requests.

Parameters: - endpoint: A string representing the API endpoint for which to fetch the supported request formats.

Returns:

• A slice of strings, where each string is a MIME type that the endpoint can accept. Example: []string{"application/json", "application/xml"}
• An error if the request could not be sent, the response could not be processed, or if the endpoint does not specify accepted formats in its response headers.

Note:

• The function makes an HTTP OPTIONS request to the given endpoint and reads the 'Accept' header in the response.
• If the 'Accept' header is not present or the OPTIONS method is not supported by the endpoint, the function returns an error.
• It is the responsibility of the caller to handle any errors and to decide on the default action if no formats are returned or in case of an error.

func (*GraphAPIHandler) GetAcceptHeader

func (u *GraphAPIHandler) 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 (*GraphAPIHandler) GetContentTypeHeader

func (u *GraphAPIHandler) GetContentTypeHeader(endpoint string) string

GetContentTypeHeader determines the appropriate Content-Type header for a given API endpoint. It checks a cache of previously fetched accepted formats for the endpoint. If the cache does not have the information, it makes an OPTIONS request to fetch and cache these formats. The function then selects the most appropriate Content-Type based on the accepted formats, defaulting to "application/json" if no specific format is found or in case of an error.

Parameters: - endpoint: The API endpoint for which to determine the Content-Type.

Returns: - The chosen Content-Type for the request, as a string.

func (*GraphAPIHandler) MarshalMultipartRequest

func (u *GraphAPIHandler) MarshalMultipartRequest(fields map[string]string, files map[string]string) ([]byte, string, error)

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

func (*GraphAPIHandler) MarshalRequest

func (u *GraphAPIHandler) MarshalRequest(body interface{}, method string, endpoint string) ([]byte, error)

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

func (*GraphAPIHandler) SetLogger

func (u *GraphAPIHandler) SetLogger(logger Logger)

SetLogger assigns a Logger instance to the UnifiedAPIHandler. This allows for logging throughout the handler's operations, enabling consistent logging that follows the configuration of the provided Logger.

func (*GraphAPIHandler) UnmarshalResponse

func (u *GraphAPIHandler) UnmarshalResponse(resp *http.Response, out interface{}) error

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