API Parameters
To access the API retrieve the Api Key and Secret Key of the event director account. This can be found under the API section on the dashboard.
- API Key
- The API key is used to identify the user account for the request being made.
- Secret Key
- The secret key is used to hash data from the client and then verified on the server. The secret key should not be shared, publicly visible or accessible.
API Wrappers
If you want to get up and running quickly then download one of our API wrappers. These contain functionality to quickly use our API.
Authentication
Each API request must contain a timestamp and authentication header. These ensure the request was sent by you and not a third party. To verify your signature you can use this online site to generate your base64 string with the secret key and compare it against your code generated signature.
Signed Request
The signed request is stored in the authentication header of the request and is composed of the API key and a base64 encoded hashed signature seperated by a period.
Authentication Header Format
{Api Key}.{Signature}
Authentication Header Example
999a99he0TR297.qEOgRhIYrXD/vPIL7AJh14lvCGGv4VVAS4ATjqCNtUo=
The message being hashed is composed of the following parameters in the following order: API key, http verb, timestamp, and the relative URI. These parameters are seperated by an ampersand (&), and should be upper case.
- API Key
- The first parameter is the API Key mentioned above.
- Http Verb
- The second parameter is the http verb of the request. This includes GET POST PUT and DELETE.
- Timestamp
- The third parameter is the timestamp and needs to be the current ISO 8601 format (2012-09-27T20:33:55.3564453Z).
- Relative URI
- The last parameter is the relative URI, /api/v1/events, of the request. This excludes the host (https://softball.exposureevents.com) and query strings (?id=1).
Signature Format
{API KEY}&{HTTP VERB}&{TIMESTAMP}&{RELATIVE URI}
Signature Example
999A99HE0TR297&GET&2012-09-27T20:33:55.3564453Z&/API/V1/EVENTS
The signature is hashed using the HMAC-SHA-256 algorithm and secret key, and base64 encoded before it's added to the request. The code below is a hashing example in .NET.
var secretKey = "m9E9pk999m9LyZ99JFNgCVb3gz8Ixojy";
// Create Message, Notice Upper Case And Ampersands Separating Parameters
var message = "999A99HE0TR297&GET&2012-09-27T20:33:55.3564453Z&/api/v1/eVENTS".ToUpper();
var key = Encoding.UTF8.GetBytes(secretKey);
string hashString;
// Create HMAC-SHA 256 Algorithm With Secret Key
using (var hmac = new HMACSHA256(key))
{
// Compute Hash From Message
var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
// Base 64 Encode
hashString = Convert.ToBase64String(hash);
}
// Return Hashed Message
return hashString;
Authentication Header Format
{API KEY}.{SIGNATURE}
Authentication Header Example
999a99he0TR297.4IyM4Cn6ZYDalubdz7SxJb0E4355KZBzQpJWieBlLns=
Authentication and Timestamp Header
After the signature is created the last thing to do is add the timestamp and authentication headers to the request. The example below is a web request with timestamp header in .NET.
var headers = new NameValueCollection
{
{ "Timestamp", "2012-09-27T20:33:55.3564453Z" },
{ "Authentication", "999a99he0TR297.4IyM4Cn6ZYDalubdz7SxJb0E4355KZBzQpJWieBlLns=" }
};
var req = WebRequest.Create("https://softball.exposureevents.com/api/v1/events") as HttpWebRequest;
req.Headers.Add(headers);
Requests and Responses
Requests and responses currently support JSON and XML, with JSON being default.
Format
When you make an API request, the response is determined by the Accept header, while the request is determined by the Content-Type header of the request. The following accept and content-type headers are available:
- JSON
- application/json
- JSON
- text/json
- XML
- application/xml
- XML
- text/xml
Http Verb
- GET requests retrieve resources.
- POST requests add resources.
- PUT requests update or perform some other action on a resource.
- DELETE requests delete a resource.
GET /api/v1/events
Timestamp: 2012-09-27T20:33:55.3564453Z
Host: softball.exposureevents.com
Accept: application/json
Content-Type: application/json
GET /api/v1/events
Timestamp: 2012-09-27T20:33:55.3564453Z
Host: softball.exposureevents.com
Accept: application/xml
Content-Type: application/xml
The request determines what to accept by looking at the Content-Type header.
{
"Id": 1,
"HomeTeamScore": null,
"HomeTeamScore": null
}
<Request>
<Id>1</Id>
<AwayTeamScore></AwayTeamScore>
<HomeTeamScore></HomeTeamScore>
</Request>
{
"Event": {
"Id": 30,
"Name": "adidas Super 64",
"Notes": null,
"Image": "https://softball.exposureevents.com/Assets/Images/973",
"StartDate": "7/25/2012",
"EndDate": "7/29/2012",
"Address": {
"StreetAddress": "1900 Searless Avenue",
"ExtendedAddress": null,
"City": "Las Vegas",
"StateRegion": "NV",
"PostalCode": "89101"
},
"Divisions": [],
"Assets": [],
"Venues": [],
"Prices": [],
}
}
<Response xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Event>
<Address>
<City>Las Vegas</City>
<PostalCode>89101</PostalCode>
<StateRegion>NV</StateRegion>
<StreetAddress>1900 Searless Avenue</StreetAddress>
</Address>
<Assets />
<Description></Description>
<Divisions />
<EndDate>7/29/2012</EndDate>
<Venues />
<Id>30</Id>
<Image>https://softball.exposureevents.com/Assets/Images/973</Image>
<Name>adidas Super 64</Name>
<Notes></Notes>
<Prices />
<Settings>
<DisplayStateWithTeam>false</DisplayStateWithTeam>
<EnableRegistration>false</EnableRegistration>
<PoolTeamStatus>2</PoolTeamStatus>
<RegistrationStatus>1</RegistrationStatus>
</Settings>
<StartDate>7/25/2012</StartDate>
</Event>
</Response>
Images
When a resource contains an image URL it can be resized dynamically by adding the querystring h for height or w for width. If both querystrings are added then the image will resize to fit within those dimenisons.
Example
https://softball.exposureevents.com/assets/images/100?h=120&w=120
Request Parameters
Name | Type | Default | Required | Description |
---|---|---|---|---|
w | string | The width of the image to be resized to. | ||
h | string | The height of the image to be resized to. |
Reports
Reports and brackets have an option to modify the output of the request to html or pdf, and an option to have it be viewable or downloadable. For brackets, you can show the original bracket without results.
Example
GET https://softball.exposureevents.com/events/pools/3143?output=pdf&download=true&results=true
Request Parameters
Name | Type | Default | Required | Description |
---|---|---|---|---|
output | enumeration | html | The output of the response. | |
download | boolean | false | The request would download the file to the client system. | |
results | boolean | true | Hide or show results in a bracket. | |
boolean | true | Hide or show print dialog for PDF. | ||
pagebreak | boolean | true | Avoids page breaks. |
Testing
GET requests can be tested in the browser. The user must be authenticated to the site, the url must be sent over SSL (https) and the api key needs to be appended to the request url.
Example
GET https://softball.exposureevents.com/api/v1/events?id=30&apikey=999A99HE0TR297
Request Parameters
Name | Type | Default | Required | Description |
---|---|---|---|---|
apikey | string | The API key. |
You can request fresh data for testing by appending a query string of r=1 where 1 is any random number. This should only be used for testing and not a live environment. We will monitor API calls to verify this is not being implemented during a real event.