How can we help you? Support is available 24 / 7 / 365

Introduction to the Highwinds APIs

The Highwinds APIs completely expose the full Highwinds CDN configuration system to users for two reasons; to allow our customers, partners, and their developers to harness and freely wield the powerful technology behind the CDN, and to encourage innovation in the delivery of excellent web experiences unencumbered by performance issues or the snares of an unsecure Internet.

At Highwinds, we seek to empower our customers to develop incredible cloud-based applications driven by one of the world’s largest global network backbones with unprecedented security advantages.

To most effectively and efficiently familiarize yourself with the Highwinds APIs, it is recommended you tackle concepts in the order in which they are laid out here. These are the basics to get you started and should be all you need to get going.

The Interactive API Documentation is a powerful resource found from within your StrikeTracker account. It can help you understand how API requests work, how the headers are structured, and how to write your own requests.
For the sake of brevity and simplicity, this guide uses cURL commands in all of its examples. Additionally, this guide assumes that you are using an administrator user to authenticate the API which has a minimum permission set of report read, configuration edit, accound edit, and content edit. If you encounter any error messages, please adjust your user’s permissions or exclude sections from this guide when writing your own API integration.

It should also be noted that StrikeTracker is built right on top of the Highwinds APIs and is the portal you may use to interact with the CDN in place of or along with programmatically interacting with the APIs, to manage your account, and configure the delivery of your content. You may find it necessary at times to make use of the StrikeTracker console, and you can learn about navigating its features here in the Support Portal.

# Full API Request Example

Here is an example API request to update an existing scope to include a Compression policy.

This example will be dissected in the sections below and used to illustrate each individual concept. Some more complex and advanced example API requests will be provided in the collapsible information boxes throughout this user guide.

curl 
-v 
-X PUT 
-H 'Content-Type: application/json' 
-H "Authorization: Bearer $STRIKETRACKER_TOKEN" 
"X-Application-Id: Foo.com"
"https://striketracker.highwinds.com/api/v1/accounts/a1b2c3d4/hosts/w5x6y7z8/configuration/654321" 
--data-binary '{"compression": {"gzip": ".js,.css"}}'

# Highwinds APIs are JSON-based RESTful APIs

The usual REST concepts are implemented:

  • GET for retrieving exisiting configurations, data, or lists of available options
  • POST for creating new configurations on a particular resource
  • PUT for updating existing configurations
  • DELETE for removing configurations

  •  

    Curl-Specific Notes and Caveats

    Curl defaults to "GET" when there is no data defined, so any requests on the "GET" verb follow the form:

    curl -H "Authorization: Bearer <token>" "https://striketracker.highwinds.com/api/<resource>"

    cURL defaults to "POST" when there is data defined via the -d or --data option. For the sake of this documentation it will be assumed that any data will reside in a file named data.json and be delivered by -d "@data.json"

    Also note that when sending data curl will default to a content type of form-data so it is necessary to set the content type manually to application/json as follows

    curl -H "Authorization: Bearer <token>" -H "Content-type: application/json" "https://striketracker.highwinds.com/api/<resource>"

    For PUT commands curl will need an explicit verb set via -X, and data and content type defined as in POST

    curl -X "PUT" -H "Authorization: Bearer <token>" -H "Content-type: application/json" "https://striketracker.highwinds.com/api/<resource>"

    For DELETE commands curl will need an explicit verb set via -X, e.g.

    curl -X "DELETE" -H "Authorization: Bearer <token>" "https://striketracker.highwinds.com/api/<resource>"

# Endpoints

All Highwinds API endpoints are subdirectories of the “striketracker.highwinds.com” root directory, and all, with the exception of a few, are performed in the context of an account and oftentimes a host, scope, or user as well.

"https://striketracker.highwinds.com/api/v1/accounts/$ACCOUNT_HASH/hosts/$HOST_HASH/configuration/$SCOPE_ID" 
Exceptions include the POST endpoint for authenticating a user or refreshing an access token, the GET and PUT for viewing and updating the logged in user, and the GET endpoints for viewing the IPs used on the CDN and currently enabled PoPs.
  •  

    Endpoint Resource Types

    RESOURCE TYPE END POINT DESCRIPTION VERBS
    Write-only authentication log in POST
    Write-only purge invalidate content from the cache POST
    Data analytics retrieve usage statistics GET
    Data platforms list Highwinds platforms available to your account GET
    Data services list services available to your account GET
    Read-write accounts read your root account and interact with subaccount configurations GET, POST, PUT, DELETE
    Read-write configuration interface with host configurations and scopes GET, POST, PUT, DELETE
    Read-write hosts interface with unique configuration sets, or "hosts" in Highwinds parlance GET, POST, PUT, DELETE
    Read-write origins interface with origin locations GET, POST, PUT, DELETE
    Read-write users interface with user profiles and permissions GET, POST, PUT, DELETE
    Reference billingRegions retrieve list of billing regions GET
    Reference docs retrieve error code lists GET
    Reference pops list the Highwinds CDN points of presence GET
    Reference version retrieve the version of the Highwinds API GET

# Account Context

Every action you’ll performed via the API is done in the context of an account.

Whether an action is being performed in the context of a subaccount or parent account, the action will be performed in the context of the account that maintains the scope you wish to perform a query on, or include a configuration policy on by using that account’s unique account hash. In most cases a host hash and scope id will be required as well.

"https://striketracker.highwinds.com/api/v1/accounts/a1b2c3d4/hosts/w5x6y7z8/configuration/654321" 
  • Accounts are represented programmatically by a unique account hash. Each account hash is alphanumeric, and is eight characters in length. Example: a1b2c3d4

  • Hosts within an account are represented by a unique hash in the same way. Example: w5x6y7z8

  • Scopes associated with a Host are represented by a unique ID that is numeric only, and six numbers long. Example: 654321

  • Users are represented by a unique ID that is numeric only, and five numbers long. Example: 54321

# Authentication

If you already have access to an administrator user profile and know the account hash for the account you’d like to query or make changes to, all you need is an access token to begin interacting with the Highwinds APIs.

Depending on your specific use case, you have two authentication options. You can authenticate a user with the use of a permanent API token, or a short-lived access token which can be revived by a refresh token.

Highwinds APIs use OAuth2. Using generic OAuth2 libraries for your programming language may make the authentication portion of your application easier to write.

To begin, you’ll need to log in to StrikeTracker to create your first API Token. That token can then be used to authenticate all future API requests, including the provisioning of additional API Tokens. You can manage both Session and API Tokens from within the context of your root StrikeTracker account or via the API.

Session Token or API Token?

If you have a simple API integration, a permanent API Token might suffice. Otherwise, if you’re building a custom application which will permit the provisioning of additional user accounts with potentially limited accessibility, you can take advantage of the Session Access and Refresh Tokens.

Create an API Token via StrikeTracker

Log In to your account and navigate to the Edit Profile / Edit User screen.

Then, Click the User Access tab near the top of the screen and your Sessions and API Tokens will be made visible to you.

API Tokens can be created and deleted. Access and Refresh Tokens can be viewed.

Create your first API Token from within StrikeTracker to begin making API requests:

  • Click the Add API Token button.
  • Then, give the token a name, enter your current password, and click Submit.

You’ve just created your first API Token which can be used to authenticate all future API requests.

Sample API request script to create a new API Token:

curl 
-v 
-X PUT 
-H 'Content-Type: application/json' 
-H "Authorization: Bearer $STRIKETRACKER_TOKEN" 
"X-Application-Id: Foo.com" 
"https://striketracker.highwinds.com/api/v1/accounts/a1b2c3d4/users/54321/tokens"  
--data-binary '{"password": “user_password", "application": “name_for_token"}'

# Importance of the X-Application-Id Header

The purpose of this header is to allow Highwinds Support to quickly debug or troubleshoot any problem you’re having should it be required.

The X-Application-Id header should be globally unique, should succeed the authorization header, and should be formatted like so:

"X-Application-Id: Foo.com"

ABOUT HIGHWINDS CUSTOMER SUPPORT

You can call us or if you prefer, you can e-mail us and create a support ticket.

We encourage you to visit our knowledgebase of important information, FAQs and how-to guides that will help you use our CDN and associated products to the fullest extent.

We also welcome your feedback, suggestions and tips on how we can make the support portal better. We appreciate your business and thank you for your interest in Highwinds.