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 unsecured 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, account 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" \
-H "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 existing 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>"Object IDs
Object IDs are unique IDs that are used by the API to perform conflict checking and can be defined in API requests to prevent multiple users/programs from attempting to modify the same object at the same time.
For example, if two users attempted to modify the same object simultaneously using a defined object ID, only the first user would receive a successful response and the second would receive an error informing them that their update did not complete.
If the users do not define an object ID, then both of them would receive a successful response. In this case, only the last update made would be applied, overwriting all of the previous ones. The second user's update would overwrite the first user's, despite both of their successful responses.
Using these IDs programmatically prevent race conditions of this kind.
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 Site, 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 | ENDPOINT | 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 Site configurations and scopes | GET, POST, PUT, DELETE |
| Read-write | Sites | interface with unique configuration sets, or "Sites" 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 a 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 perform 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 Site 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
-
Sites within an account are represented by a unique hash in the same way. Example: w5x6y7z8
-
Scopes associated with a Site 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 that 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"