API Reference
- Jonathan Cohen
Overview
The USTA API provides a toolkit for accessing USTA data from properly credentialed partner applications. The API is organized around RESTful calling style that works with standard HTTP calls. All requests should be made over SSL. All requests and responses as well as errors are encoded in JSON. This document provides developers with an introduction to integrating your application with the USTA API.
API Scopes
The USTA API is broken up in three types of requests:
- Bound requests are for accessing data pertaining to the account that is currently logged in. This is designed for access from the browser (client).
- Unbound requests are for accessing data pertaining to any USTA account. This is designed to for server side machine-to-machine access.
- Reference requests are for accessing metadata not pertaining to any account.
Authentication
USTA uses AWS Cognito as the Identity Provider. Bound access uses Authentication Code bearer token paradigm. Unbound access uses Basic Auithentication. Examples of both can be found here.
Credentials
This is a secure API and requires credentials to accessing the data. The USTA must issue credentials prior to using the API. If you require credentials, please contact USTA.
Endpoints
The simplest way to access the API is via use of cURL. Any language or client that supports HTTPS can be used to call the API.
Lookup Behavior
Standard behavior when looking up elements in the API result in HTTP error status 404 NOT FOUND when an element does not exist. In some cases, an API can result in HTTP status 200 where the result will contain an empty result set. Where the behavior deviates, the API reference will denote the behavior,
Error Codes
The USTA API follows standard HTTP error status protocols. Please note that all valid responses will return an HTTP status code of 200.
You can see the complete list of error codes here.
Rate Limiting
The USTA institutes rate limits over a 5 minute time horizon. Traffic is limited on both an overall message and per endpoint basis
Rate limited calls may result in HTTP error status 429 TOO MANY REQUESTS responses once the limit is reached. Once the time horizon has expired, the count will be reset and responses will resume. This cycle will repeat indifinitely.
Overall Traffic Limit
Traffic originating from each origin is restricted so as to prevent denial of service events.
| Item | Value | Description |
|---|---|---|
| Time Horizon | 5 Minutes | Period of time after which the limit count will reset. |
| Limit | 10,000 Requests | Maximum requests a distinct caller can make within the time horizon. |
| Response Code | 429 | HTTP code after limit is reached |
Per API Call Limit
Calls tp individual API endpoints fro each origin is restriucted
| Item | Value | Description |
|---|---|---|
| Time Horizon | 5 Minutes | Period of time after which the limit count will reset. |
| Limit | 100 Requests | Maximum requests a distinct caller can make within the time horizon. |
| Response Code | 429 | HTTP code after limit is reached |
Pagination
The USTA API supports pagination where indicated in the Swagger document. Pagination is used to increase cliient application performance by reducing the amount of data dragged across the wire. For api calls that respond with large data sets, USTA supports an Offset/PageSize paradigm. The result set is broken up in pages containing the specified number of documents per page. The client applicationn increases the page number until the response contains less than pageSize. Once the response contains less than pageSize, processing for this call has completed.
"pagination": { "currentPage":1, "pageSize": 20}