This guide should serve to inform experienced developers of the logic behind Highwinds APIs
StrikeTracker is built right on top of Highwinds APIs. If you already have access to a user profile and know the account hash for the account you’d like to make changes to, all you need is an access token and you can begin interacting with the APIs.
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.
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:
curl -v -X PUT -H 'Content-Type: application/json' -H "Authorization: Bearer $STRIKETRACKER_TOKEN" "X-Application-Id: Foo.com" [rest of request]
Account Context, Hashes, and IDs
Every action you’ll perform with the API will be performed 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 you intend to affect a change to and by using that account’s unique account hash.
-
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 Sites 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
Endpoints
All API endpoints are subdirectories of the striketracker.highwinds.com root directory.
For example, if I wanted to add a Compression policy on one particular scope, or more accurately, update an existing scope to include a Compression policy, for targeting all files with extensions “.js” and “.css,” the Endpoint URL including the account hash, Site hash, and scope id would look something like this:
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”}}'
Authentication
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 to interact with the Highwinds API, you can take advantage of the Session Access and Refresh Tokens.
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"}'