domainreputation

README

Overview

The client library for Domain Reputation API in Go language.

The minimum go version is 1.17.

Installation

The library is distributed as a Go module

go get github.com/whois-api-llc/domain-reputation-go

Examples

Full API documentation available here

You can find all examples in example directory.

Create a new client

To start making requests you need the API Key. You can find it on your profile page on whoisxmlapi.com. Using the API Key you can create Client.

Most users will be fine with NewBasicClient function.

client := domainreputation.NewBasicClient(apiKey)

If you want to set custom http.Client to use proxy then you can use NewClient function.

transport := &http.Transport{Proxy: http.ProxyURL(proxyUrl)}

client := domainreputation.NewClient(apiKey, domainreputation.ClientParams{
    HTTPClient: &http.Client{
        Transport: transport,
        Timeout:   20 * time.Second,
    },
})

Make basic requests

Domain Reputation API lets you calculate a domain's reputation scores based on hundreds of parameters.

// Make request to get the Domain Reputation API response as a model instance.
domainReputationResp, _, err := client.Get(ctx, "whoisxmlapi.com")
if err != nil {
    log.Fatal(err)
}

log.Println(domainReputationResp.Mode, domainReputationResp.ReputationScore)

// Make request to get raw data in XML.
resp, err := client.GetRaw(context.Background(), "whoisxmlapi.com",
    domainreputation.OptionOutputFormat("XML"))
if err != nil {
    log.Fatal(err)
}

log.Println(string(resp.Body))

Documentation

Index

• type ArgError
  • func (a *ArgError) Error() string
• type Client
  • func NewBasicClient(apiKey string) *Client
  • func NewClient(apiKey string, params ClientParams) *Client
  • func (c *Client) Do(ctx context.Context, req *http.Request, v io.Writer) (response *http.Response, err error)
  • func (c *Client) NewRequest(method string, u *url.URL, body io.Reader) (*http.Request, error)
• type ClientParams
• type DomainReputationResponse
• type DomainReputationService
• type ErrorMessage
  • func (e *ErrorMessage) Error() string
• type ErrorResponse
  • func (e *ErrorResponse) Error() string
• type Option
  • func OptionMode(mode string) Option
  • func OptionOutputFormat(outputFormat string) Option
• type Response
• type TestResult
• type Warning

Types

type ArgError

type ArgError struct {
	Name    string
	Message string
}

ArgError is the argument error.

func (*ArgError) Error

func (a *ArgError) Error() string

Error returns error message as a string.

type Client

type Client struct {

	// DomainReputation is an interface for Domain Reputation API
	DomainReputationService
	// contains filtered or unexported fields
}

Client is the client for Domain Reputation API services.

func NewBasicClient

func NewBasicClient(apiKey string) *Client

NewBasicClient creates Client with recommended parameters.

func NewClient

func NewClient(apiKey string, params ClientParams) *Client

NewClient creates Client with specified parameters.

func (*Client) Do

func (c *Client) Do(ctx context.Context, req *http.Request, v io.Writer) (response *http.Response, err error)

Do sends the API request and returns the API response.

func (*Client) NewRequest

func (c *Client) NewRequest(method string, u *url.URL, body io.Reader) (*http.Request, error)

NewRequest creates a basic API request.

type ClientParams

type ClientParams struct {
	// HTTPClient is the client used to access API endpoint
	// If it's nil then value API client uses http.DefaultClient
	HTTPClient *http.Client

	// DomainReputationBaseURL is the endpoint for 'Domain Reputation API' service
	DomainReputationBaseURL *url.URL
}

ClientParams is used to create Client. None of parameters are mandatory and leaving this struct empty works just fine for most cases.

type DomainReputationResponse

type DomainReputationResponse struct {
	// Mode is the selected test mode.
	Mode string `json:"mode"`

	// ReputationScore is the composite safety score based on numerous security data sources.
	ReputationScore float64 `json:"reputationScore"`

	// TestResults is a part of the Domain Reputation API response containing the test results.
	TestResults []TestResult `json:"testResults"`
}

DomainReputationResponse is a response of Domain Reputation API.

type DomainReputationService

type DomainReputationService interface {
	// Get returns parsed Domain Reputation API response.
	Get(ctx context.Context, domainName string, opts ...Option) (*DomainReputationResponse, *Response, error)

	// GetRaw returns raw Domain Reputation API response as the Response struct with Body saved as a byte slice.
	GetRaw(ctx context.Context, domainName string, opts ...Option) (*Response, error)
}

DomainReputationService is an interface for Domain Reputation API.

type ErrorMessage

type ErrorMessage struct {
	Code    int    `json:"code"`
	Message string `json:"messages"`
}

ErrorMessage is the error message.

func (*ErrorMessage) Error

func (e *ErrorMessage) Error() string

Error returns error message as a string.

type ErrorResponse

type ErrorResponse struct {
	Response *http.Response
	Message  string
}

ErrorResponse is returned when the response status code is not 2xx.

func (*ErrorResponse) Error

func (e *ErrorResponse) Error() string

Error returns error message as a string.

type Option

type Option func(v url.Values)

Option adds parameters to the query.

func OptionMode

func OptionMode(mode string) Option

OptionMode sets the check mode. API can check your domain in 2 modes: 'fast' - Only select codes will run—i.e., 62 WHOIS Domain status, 82 Malware Databases check, 87 SSL certificate validity, and 93 WHOIS Domain check—while other tests and data collectors will be disabled. 'full' - all the data and the tests will be processed. Acceptable values: fast | full. Default: fast.

func OptionOutputFormat

func OptionOutputFormat(outputFormat string) Option

OptionOutputFormat sets Response output format JSON | XML. Default: JSON.

type Response

type Response struct {
	*http.Response

	// Body is the byte slice representation of http.Response Body
	Body []byte
}

Response is the http.Response wrapper with Body saved as a byte slice.

type TestResult

type TestResult struct {
	// Test is the test name which reduced the final score.
	Test string `json:"test"`

	// TestCode is the unique numeric test identifier.
	TestCode int `json:"testCode"`

	// Warnings is the list of warnings detected during the test execution.
	Warnings []Warning `json:"warnings"`
}

TestResult is a part of the Domain Reputation API response containing the test results.

type Warning

type Warning struct {
	// WarningDescription is the warning description.
	WarningDescription string `json:"warningDescription"`

	// Warning code is the unique numeric warning codes.
	WarningCode int `json:"warningCode"`
}

Warning is the warning detected during the test execution.