Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

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

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 per-month, per-hour, per-minute, and per-IP rate limits for each API method, and limits API users to a maximum of five concurrent connections from a single IP address. Our default limits are more than sufficient for nearly all use cases.  Please be mindful of these limits.  

Rate limited calls may result in HTTP error status 429 TOO MANY REQUESTS responses.

Pagination*

The default records returned per call is (up to) 25, and the maximum number that can be returned is 100. We provide limit and offset parameters to allow navigation through larger data sets. Responses include a count field, which specifies the total number of records available via pagination. For performance reasons, the offset parameter is limited to a maximum value of 50000.

Here's an example of sequential requests to paginate through the most recent 300 listings, 50 at a time:

https://services.usta.com/v1/customer/me/roles?limit=50&offset=0
https://services.usta.com/v1/customer/me/roles?limit=50&offset=50
https://services.usta.com/v1/customer/me/roles?limit=50&offset=100
https://services.usta.com/v1/customer/me/roles?limit=50&offset=150
https://services.usta.com/v1/customer/me/roles?limit=50&offset=200
https://services.usta.com/v1/customer/me/roles?limit=50&offset=250
  • No labels