Go SDK for EdgeCast CDN
The official Go SDK for interacting with EdgeCast APIs.
Jump To:
Dependencies
Installing
$GOPATH
To install the SDK into your $GOPATH:
go get -u github.com/EdgeCast/ec-sdk-go
Go Modules
go get github.com/EdgeCast/ec-sdk-go
Using the SDK
Simply 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.
Customer Management
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
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
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)
// ...
Edge CNAME
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)
// ...
Customer Origin
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
-> 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.
Origin Groups
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)
Customer Origin Entry (v3)
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)
Load Balancing
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)
-> 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.
Master Server Group
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)
// ...
Real Time Log Delivery (RTLD)
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.
Real-Time Log Delivery Rate Limiting (RTLD Rate Limiting)
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)
// ...
Rules Engine
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)
// ...
Web Application Firewall (WAF)
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.
Access Rules
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.
Bot Rule Sets
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.
Custom Rule Sets
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
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
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.
WAF Sample Usage
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},
})
Structure
.
├── 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.
Contributing
Please refer to the contributing.md
file for information about how to get involved.
We welcome issues, questions, and pull requests.
Maintainers
Resources
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.