The official Go SDK for interacting with EdgeCast APIs.
Jump To:
- Go 1.19
To install the SDK into your $GOPATH:
go get -u github.com/EdgeCast/ec-sdk-gogo get github.com/EdgeCast/ec-sdk-goSimply import the SDK and provide the API credentials provided to you. They may be an API Token or OAuth 2.0 Credentials. Examples are listed below for each feature.
Our Customer Management service provides administrative operations to manage Customer accounts and Customer User accounts for a Partner. These operations allow a partner to automate administrative tasks on their customers and customer user accounts.
To use this Customer Management service, use the API Token provided to you.
Customer Account Management Operations allows management of customer accounts
import (
"github.com/EdgeCast/ec-sdk-go/edgecast"
"github.com/EdgeCast/ec-sdk-go/edgecast/customer"
)
// ...
sdkConfig := edgecast.NewSDKConfig()
sdkConfig.APIToken = "MY API TOKEN"
customerService, err := customer.New(sdkConfig)
newCustomer := customer.Customer{
// ...
}
addParams := customer.NewAddCustomerParams()
addParams.Customer = newCustomer
resp, err := customerService.AddCustomer(*addParams)
// ...Customer User Account Management Operations allows you to manage user accounts under a (parent) customer.
import (
"github.com/EdgeCast/ec-sdk-go/edgecast"
"github.com/EdgeCast/ec-sdk-go/edgecast/customer"
)
// ...
sdkConfig := edgecast.NewSDKConfig()
sdkConfig.APIToken = "MY API TOKEN"
customerService, err := customer.New(sdkConfig)
customerUser := customer.CustomerUser{
// ...
}
addParams := customer.NewAddCustomerUserParams()
addParams.CustomerUser = customerUser
// ...
resp, err := customerService.AddCustomerUser(*addParams)
// ...Our User-Friendly URL, also known as Edge CNAME, takes advantage of an Edge CNAME configuration and a CNAME record to provide a friendlier alternative to a CDN URL. An edge CNAME URL is specific to the platform from which it was configured.
For more information, please read the official documentation for Edge CNAME
To use the edge CNAME service, use the API Token provided to you.
import (
"github.com/EdgeCast/ec-sdk-go/edgecast"
"github.com/EdgeCast/ec-sdk-go/edgecast/edgecname"
)
// ...
sdkConfig := edgecast.NewSDKConfig()
sdkConfig.APIToken = "MY API TOKEN"
edgecnameService, err := edgecname.New(sdkConfig)
cname := edgecname.EdgeCname{
// ...
}
addParams := edgecname.NewAddEdgeCnameParams()
addParams.EdgeCname = cname
// ...
resp, err := edgecnameService.AddEdgeCname(*addParams)
// ...Our Customer Origin Service allows you to serve content stored or generated by third-party web servers (e.g., web hosting) via the CDN by:
- Creating a customer origin configuration. This type of configuration maps one or more servers to a CDN URL.
- (Optional) Creating an edge CNAME configuration that allows you to serve traffic via the CDN without having to update your links. This type of configuration maps a customer origin configuration to a CNAME record.
For more information, please read the official documentation for Customer Origin
To use the Customer Origins service, use the API Token provided to you.
import (
"github.com/EdgeCast/ec-sdk-go/edgecast"
"github.com/EdgeCast/ec-sdk-go/edgecast/edgecname"
)
// ...
sdkConfig := edgecast.NewSDKConfig()
sdkConfig.APIToken = "MY API TOKEN"
originService, err := origin.New(sdkConfig)
newOrigin := origin.Origin{
// ...
}
addParams := origin.NewAddOriginParams()
// ...
addParams.Origin = newOrigin
resp, err := originService.AddOrigin(*addParams)
// ...-> Customer Origin v3 is currently available as a BETA. Business-critical processes should not depend on this functionality.
Customer Origin v3 uses dedicated endpoints to manage a customer origin group and origin entries. This allows you to manage a customer origin group and all of its entries using multiple requests rather than in a single request.
It also supports managing a customer origin group's TLS configuration and retrieval of the Function@Edge functions associated with your customer origin groups.
For more information, please read the official documentation for Customer Origin v3.
For detailed code examples, please refer to the examples directory.
Create Origin Groups using the platform specific namespace within the OriginV3 Service. See below for an example of creating an HTTP Large Origin Group.
// Set up the creation model.
tlsSettings := originv3.TlsSettings{
PublicKeysToVerify: []string{
"ff8b4a82b08ea5f7be124e6b4363c00d7462655f",
"c571398b01fce46a8a177abdd6174dfee6137358",
},
}
tlsSettings.SetAllowSelfSigned(false)
tlsSettings.SetSniHostname("origin.example.com")
grp := originv3.CustomerOriginGroupHTTPRequest{
Name: "test group",
TlsSettings: &tlsSettings,
}
grp.SetHostHeader("override-hostheader.example.com")
grp.SetNetworkTypeId(2) // Prefer IPv6 over IPv4
grp.SetStrictPciCertified(false) // Allow non-PCI regions
// Set params and add the new group.
addParams := originv3.NewAddHttpLargeGroupParams()
addParams.CustomerOriginGroupHTTPRequest = grp
addResp, err := svc.HttpLargeOnly.AddHttpLargeGroup(addParams)Add an origin entry to a customer origin group for either platform. See below for an example of creating an HTTP Large Customer Origin Entry. For a detailed example, please refer to the examples directory.
addParams := originv3.NewAddOriginParams()
addParams.MediaType = enums.HttpLarge.String()
originRequest := originv3.NewCustomerOriginRequest(
"cdn-origin-example.com",
false,
groupID,
)
addParams.CustomerOriginRequest = *originRequest
addResp, err := svc.Common.AddOrigin(addOriginParams)Update a customer origin group's failover order through a platform-specific endpoint.
Key information:
- Sort order is defined on a per protocol basis.
- If you create an origin entry that is configured to match the client's protocol (protocol_type_id=3), then our service will create an HTTP and an HTTPS version of it. Each of these origin entries may be assigned a different sort order.
- Ensure that sort order is applied as intended by defining a sort position for all of the customer origin group's origin entries that correspond to the desired protocol (i.e., HTTP or HTTPS). Defining a sort position for a subset of origin entries that correspond to that protocol may produce unexpected results.
failoverParams := originv3.NewUpdateFailoverOrderParams()
failoverParams.MediaType = enums.HttpLarge.String()
failoverParams.GroupId = groupID
failoverParams.FailoverOrder = []originv3.FailoverOrder{
{
Id: origin1ID,
Host: "http://cdn-origin-example.com",
FailoverOrder: 0,
},
{
Id: origin2ID,
Host: "http://cdn-origin-example2.com",
FailoverOrder: 2,
},
{
Id: origin3ID,
Host: "http://cdn-origin-example3.com",
FailoverOrder: 1,
},
}
err = svc.Common.UpdateFailoverOrder(failoverParams)-> Route (DNS) is currently available as a BETA. Business-critical processes should not depend on this functionality.
Our Route (DNS) solution is a reliable, high performance, and secure DNS service that provides capabilities such as:
- Load balance traffic for a CNAME record or a subdomain for a primary zone hosted on another DNS system.
- Establish a failover system for a CNAME record or a subdomain for a primary zone hosted on another DNS system.
- Create a standard DNS zone. Optionally, load balance or failover requests to that zone.
- Import a secondary DNS zone by creating a master server group and a secondary zone group.
- Verify a server's capability to fulfill requests through health checks performed from around the world.
For more information, please read the official documentation for Route (DNS)
To use the Route(DNS) service, use the API Token provided to you.
A master server group allows quick and easy management of master name servers, while a secondary zone group defines the secondary zones that will be imported from servers defined in a master server group and any TSIG keys that should be used for the zone transfer.
import (
"github.com/EdgeCast/ec-sdk-go/edgecast"
"github.com/EdgeCast/ec-sdk-go/edgecast/routedns"
)
// ...
sdkConfig := edgecast.NewSDKConfig()
sdkConfig.APIToken = "MY API TOKEN"
routeDNSService, err := routedns.New(sdkConfig)
masterServerGroup := buildMasterServerGroup()
addParams := routedns.NewAddMasterServerGroupParams()
addParams.MasterServerGroup = masterServerGroup
// ...
resp, err := routeDNSService.AddMasterServerGroup(*addParams)
// ...Our Real-Time Log Delivery (RTLD) service delivers log data in near real-time to a variety of destinations.
For more information, please read the official documentation for Real-Time Log Delivery (RTLD).
To use the Rules Engine service, use OAuth 2.0 Credentials.
Delivers log data that describes requests for which Web Application Firewall (WAF) enforced a rate limit as defined through a rate rule.
import (
"github.com/EdgeCast/ec-sdk-go/edgecast"
"github.com/EdgeCast/ec-sdk-go/edgecast/waf"
)
// ...
idsCredentials := edgecast.IDSCredentials{
ClientID: clientID,
ClientSecret: clientSecret,
Scope: scope,
}
sdkConfig := edgecast.NewSDKConfig()
sdkConfig.IDSCredentials = idsCredentials
rtldService, err := rtld.New(sdkConfig)
addParams := profiles_rl.NewProfilesRateLimitingAddCustomerSettingParams()
addParams.SettingDto = &rtldmodels.RateLimitingProfileDto{
// ...
}
addResp, err :=
rtldService.ProfilesRl.ProfilesRateLimitingAddCustomerSetting(addParams)
// ...Our Rules Engine allows the customization of requests handled by our CDN. Sample customizations that may be performed are:
Override or define a custom cache policy Secure or deny requests for sensitive content Redirect requests to a different URL
For more information, please read the official documentation for Custom Request Handling via Rules Engine.
To use the Rules Engine service, use OAuth 2.0 Credentials. A Policy should be constructed as a JSON object passed as a string.
import (
"github.com/EdgeCast/ec-sdk-go/edgecast"
"github.com/EdgeCast/ec-sdk-go/edgecast/waf"
)
// ...
policyString := `{
// ...
}`
idsCredentials := edgecast.IDSCredentials{
ClientID: clientID,
ClientSecret: clientSecret,
Scope: scope,
}
sdkConfig := edgecast.NewSDKConfig()
sdkConfig.IDSCredentials = idsCredentials
rulesengineService, err := rulesengine.New(sdkConfig)
addParams := rulesengine.NewAddPolicyParams()
addParams.PolicyAsString = policyString
addPolicyResp, err := rulesengineService.AddPolicy(*addParams)
// ...Our WAF service provides a layer of security between many security threats and your external web infrastructure. WAF increases security by monitoring, detecting, and preventing application layer attacks. It inspects inbound HTTP/HTTPS traffic against reactive and proactive security policies and blocks malicious activity in-band and on a real-time basis.
For more information, please read the official documentation for Web Application Firewall (WAF).
To use the WAF service, use the API Token provided to you.
An access rule identifies legitimate traffic and threats by ASN, Cookie, Country, IP Address, Referrer, URL, User agent, HTTP method, Media type, File extension, and Request headers.
For detailed information about Access Rules in WAF, please read the official documentation.
Use bot rules to require a client (e.g., a web browser) to solve a challenge before resolving the request. WAF blocks traffic when the client cannot solve this challenge within a few seconds. Basic bots typically cannot solve this type of challenge, and therefore their traffic is blocked. This prevents them from scraping your site, carding, spamming your forms, launching DDoS attacks, and committing ad fraud.
For detailed information about Bot Rules in WAF, please read the official documentation.
Use custom rules to tailor how WAF identifies malicious traffic. This provides added flexibility for threat identification that allows you to target malicious traffic with minimal impact on legitimate traffic. Custom threat identification combined with rapid testing and deployment enables you to quickly address long-term and zero-day vulnerabilities.
For detailed information about Custom Rules in WAF, please read the official documentation.
Managed Rules identify malicious traffic via predefined rules. A collection of policies and rules is known as a rule set.
For detailed information about Managed Rules in WAF, please read the official documentation.
Rate Rules restricts the flow of site traffic with the intention of:
- Diverting malicious or inadvertent DDoS traffic.
- Preventing a customer origin server from being overloaded.
- Requests that exceed the rate limit may be dropped, redirected to another URL, or sent a custom response.
For detailed information about Rate Rules in WAF, please read the official documentation.
import (
"github.com/EdgeCast/ec-sdk-go/edgecast"
"github.com/EdgeCast/ec-sdk-go/edgecast/waf"
"github.com/EdgeCast/ec-sdk-go/edgecast/waf/rules/access"
"github.com/EdgeCast/ec-sdk-go/edgecast/waf/rules/bot"
"github.com/EdgeCast/ec-sdk-go/edgecast/waf/rules/custom"
"github.com/EdgeCast/ec-sdk-go/edgecast/waf/rules/managed"
"github.com/EdgeCast/ec-sdk-go/edgecast/waf/rules/rate"
"github.com/EdgeCast/ec-sdk-go/edgecast/waf/scopes"
)
// ...
sdkConfig := edgecast.NewSDKConfig()
sdkConfig.APIToken = "MY API TOKEN"
wafService, err := waf.New(sdkConfig)
accountNumber := "ACCOUNT_NUMBER"
accessRuleID, err := wafService.AccessRules.AddAccessRule(
access.AddAccessRuleParams{
AccountNumber: accountNumber,
AccessRule: access.AccessRule{
// ...
}
})
botRuleSetID, err = wafService.BotRuleSets.AddBotRuleSet(
bot.AddBotRuleParams{
AccountNumber: accountNumber,
BotRuleSet: bot.BotRuleSet{
// ...
},
})
customRuleSetID, err = wafService.CustomRuleSets.AddCustomRuleSet(
custom.AddCustomRuleSetParams{
AccountNumber: accountNumber,
CustomRuleSet: custom.CustomRuleSet{
// ...
},
})
managedRuleID, err = wafService.ManagedRules.AddManagedRule(
managed.AddManagedRuleParams{
AccountNumber: accountNumber,
ManagedRule: managed.ManagedRule{
// ...
},
})
rateRuleID, err = wafService.RateRules.AddRateRule(
rate.AddRateRuleParams{
AccountNumber: accountNumber,
RateRule: rate.RateRule{
// ...
},
})
scope := scopes.Scope{
Host: scopes.MatchCondition{
// ...
},
Limits: &[]scopes.Limit{
{
ID: rateRuleID,
Action: scopes.LimitAction{
// ...
},
},
},
ACLProdID: &accessRuleID,
ACLProdAction: &scopes.ProdAction{
// ...
},
ProfileProdID: &managedRuleID,
ProfileProdAction: &scopes.ProdAction{
// ...
},
RuleProdID: &customRuleSetID,
RuleProdAction: &scopes.ProdAction{
// ...
},
BotsProdID: &botRuleSetID,
BotsProdAction: &scopes.ProdAction{
// ...
},
}
modifyAllScopesResp, err := wafService.Scopes.ModifyAllScopes(
&scopes.Scopes{
CustomerID: accountNumber,
Scopes: []scopes.Scope{scope},
})Bot Manager Advanced adds an additional layer of security that is dedicated to bot detection and mitigation. It is designed to automatically detect good bots (e.g., search bots) and bad bots, including those that spoof good bots, by analyzing requests and behavior. You may even customize how bad bots are detected and mitigated by defining custom criteria that profiles a bad bot and the action that we will take for that traffic. Bot Manager Advanced is also able to mitigate basic bots by requiring a web browser to resolve a JavaScript challenge before our service will resolve traffic. Finally, it provides actionable near real-time data on detected bots through which you may fine-tune your configuration to reduce false positives.
Bot Manager Advanced is a powerful tool through which you may mitigate undesired bot traffic and prevent them from performing undesired or malicious activity, such as scraping your site, carding, taking over accounts through credential stuffing, spamming your forms, launching DDoS attacks, and committing ad fraud.
For detailed information about Bot Manager in WAF, please read the official documentation.
import (
"github.com/EdgeCast/ec-sdk-go/edgecast"
"github.com/EdgeCast/ec-sdk-go/edgecast/waf_bot_manager"
)
// ...
sdkConfig := edgecast.NewSDKConfig()
sdkConfig.APIToken = "MY API TOKEN"
wafBotManagerService, err := waf_bot_manager.New(sdkConfig)
customerID := "<Customer ID>"
botRuleID := "<Bot Rule ID>"
botmanager := waf_bot_manager.BotManager{
Name: waf_bot_manager.PtrString("my bot manager"),
SpoofBotActionType: waf_bot_manager.PtrString("ALERT"),
Actions: &waf_bot_manager.ActionObj{
ALERT: &waf_bot_manager.AlertAction{
// ...
},
BLOCK_REQUEST: &waf_bot_manager.BlockRequestAction{
// ...
},
BROWSER_CHALLENGE: &waf_bot_manager.BrowserChallengeAction{
// ...
},
CUSTOM_RESPONSE: &waf_bot_manager.CustomResponseAction{
// ...
},
REDIRECT302: &waf_bot_manager.RedirectAction{
// ...
},
RECAPTCHA: &waf_bot_manager.RecaptchaAction{
// ...
},
},
BotsProdId: &botRuleID,
CustomerId: &customerID,
ExceptionCookie: []string{"sample cookie"},
ExceptionJa3: []string{"sample ja3"},
ExceptionUrl: []string{"sample url"},
ExceptionUserAgent: []string{"sample user agent"},
InspectKnownBots: waf_bot_manager.PtrBool(true),
KnownBots: []waf_bot_manager.KnownBotObj{
{
// ...
},
},
}
createBotManagerParams := waf_bot_manager.NewCreateBotManagerParams()
createBotManagerParams.CustId = customerID
createBotManagerParams.BotManagerInfo = &botmanager
createBotManagerResp, err := svc.BotManagers.CreateBotManage(createBotManagerParams).
├── edgecast
package containing the main functionality for sdk.
Please add new client and model folders for new services here.
│ ├── eclog
defines the the implementation and helper methods for logging
│ ├── internal
package containing helper methods and shared functionality used in sdk
please add new helper methods here
│ │ ├── collectionhelper
helper methods for working with aggregate/collection types
│ │ ├── jsonhelper
helper methods for working with json
│ │ ├── testhelper
helper methods used in testing
│ │ ├── ecauth
authentication layer for oauth 2.0 and token based authentication
│ │ └── ecclient
package client provides a base client implementation for interacting
with edgecast cdn apis.
configuration and authentication types are also provided.
│ ├── customer
client files for interacting with customer api
model files for customer
│ ├── edgecnamee
client files for interacting with edge cname api
model files for edge cnamee
│ ├── origin
client files for interacting with customer origin api
model files for customer origin
│ ├── originv3
client files for interacting with customer origin v3 api
model files for customer origin
│ ├── routedns
client files for interacting with route (dns)
model files for route (dns)
│ ├── rtld
client files for interacting with real time log delivery api
│ ├── rtldmodels
model files for real time log delivery
│ ├── rulesengine
client files for interacting with rules engine api
model files for rules engine
│ ├── waf
client files for interacting with waf api
model files for waf
│ ├── shared
shared models and enums
│ ├── config
defines the configuration of sdk services
│ ├── doc
please add new docs here as needed
│ └── version
lists the latest version of sdk
├── example
example files to get started using the services
├── template
template files used to generate client files and models using swagger api
documentation
└── Makefile
This Makefile should contain all testing and building operations.
Please refer to the contributing.md file for information about how to get involved. We welcome issues, questions, and pull requests.
- Frank Contreras: frank.contreras@edgecast.com
- Steven Paz: steven.paz@edgecast.com
- Shikha Saluja: shikha.saluja@edgecast.com
CDN Reference Documentation - This is a useful resource for learning about EdgeCast CDN. It is a good starting point before using this SDK.
API Documentation - For developers that want to interact directly with the EdgeCast CDN API, refer to this documentation. It contains all of the available operations as well as their inputs and outputs.
Examples - Examples to get started can be found here.
Submit an Issue - Found a bug? Want to request a feature? Please do so here.