API Overview

api overview the ampeducator api provides developers with access to a large subset of ampeducator features, allowing you to access and interact with data in your institution's account for a complete list of available resources, endpoints, parameters, and response objects, see the ampeducator developer api reference before you begin before using the api, an administrator must enable api access under institution config generate or copy the institution's api key from institution config keep your api key secure your api key provides access to your institution's data and should not be shared or exposed in client side code making an api request api requests are made using the following endpoint structure https //{purl} ampeducator com/api/{resource}/{action} where {purl} is your institution's unique ampeducator identifier {resource} identifies the section of the application you are accessing {action} identifies the operation you want to perform {parameters} are any additional values required by the action each endpoint in the developer api reference specifies whether it requires a get or post request and which parameters are required authentication your institution's api key is required to authenticate requests the api key can be provided using an http bearer token authorization bearer {apikey} for endpoints that accept parameters, the api key may also be included as a request parameter https //{purl} ampeducator com/api/{resource}/{action}?apikey={apikey}&{parameters} form encoded post request curl x post \\ "https //{purl} ampeducator com/api/{resource}/{action}" \\ h "content type application/x www form urlencoded" \\ h "authorization bearer {apikey}" \\ d "{parameters}" json post requests endpoints that accept post requests can also receive a json object as the request body use the following headers authorization bearer {apikey} content type application/json example curl x post \\ "https //{purl} ampeducator com/api/{resource}/{action}" \\ h "content type application/json" \\ h "authorization bearer {apikey}" \\ d '{ json object }' api responses the api returns responses as json a typical response follows this structure { "responsecode" 200, "messages" { "general" \[], "warning" \[], "errors" \[], "witherrors" false, "totalmessages" 0 }, "action" "string", "query" {}, "body" "string", "page" 1, "totalpages" 1, "totalrecords" 0, "totalms" 0, "data" \[] } response fields responsecode — the http response code returned for the requested action messages — general, warning, and error messages related to the request action — the action that was requested query — the parsed query parameters body — the contents of the request body page — the current page of returned data totalpages — the total number of pages available totalrecords — the total number of objects available totalms — the total queue and execution time in milliseconds data — the objects returned by the api always check the messages object for warnings or errors that may provide additional information about the request response codes the api may return the following http response codes pagination and ordering the api returns a maximum of 100 objects per request each response includes totalpages, which indicates how many pages of results are available to retrieve a specific page, pass the page parameter \&page=2 or in a json request { "page" 2 } continue requesting pages only until you reach the reported totalpages ordering results results can be ordered using orderby and orderdir for example \&orderby=studentid\&orderdir=asc or { "orderby" "studentid", "orderdir" "asc" } orderdir accepts asc or desc when ordering paginated results, use a field with unique values where possible ordering by a field containing duplicate values may cause the order of results to change between requests request handling and rate limits api requests are managed on a per institution basis to maintain reliable performance for all institutions concurrent requests if multiple api requests are submitted by the same institution at the same time, they are queued and processed one at a time, in the order received , rather than being processed concurrently typical api usage should not be affected however, large bursts of concurrent requests will take longer to fully complete because later requests must wait for earlier requests to finish each institution has a limited request queue if too many requests are waiting at once, additional requests will receive http 429 too many requests a request that waits too long in the queue may receive http 504 gateway timeout if either occurs, wait briefly before retrying the request if the issue continues, reduce the number of concurrent requests and increase the delay between retries rate limiting in addition to request queuing, each institution is subject to a request rate limit rate limiting is designed to prevent continuous, high frequency api calls this is separate from the concurrent request queue an integration may encounter the rate limit even if it is sending requests one at a time if the rate limit is exceeded, additional requests will receive an http 429 response until the request rate decreases exact rate limits are not published and may be adjusted over time integrations making occasional or moderately paced requests, including reasonable bursts of requests, should not normally encounter this limit working with large data sets when working with larger amounts of data use batch or filtered endpoints where available instead of requesting individual records one at a time use pagination to retrieve large result sets and stop requesting pages once you reach totalpages avoid large bursts of concurrent requests add pacing between requests when a batch option is not available implement retry with backoff for temporary 429 and 504 responses for example, if a request receives a 429, wait briefly before retrying if repeated attempts continue to fail, progressively increase the delay rather than immediately sending the request again report generation additional limits apply when generating reports through the api a report can be regenerated through the api at most once per hour, per report if /report/generate is called again for the same report before one hour has passed since it was last generated, ampeducator will return the most recently generated version instead of starting another report generation job the request will still return a successful 200 response and will include a warning message indicating that the existing report was returned this cooldown applies only to automated api requests generating a report manually in ampeducator is not affected if your integration calls /report/generate, always check the messages object for warnings as well as errors report downloads the /report/download endpoint is being deprecated report downloads currently return the report file as base64 encoded data directly in the api response this approach is being replaced with a new endpoint that will return a short lived download url instead /report/download will continue to work during the transition period details about the new endpoint, migration process, and sunset date for /report/download will be provided separately integrations using /report/download should plan to migrate once the replacement endpoint becomes available testing an api call a simple api request can be useful when confirming your api key and institution url for example https //{purl} ampeducator com/api/location/get?apikey={apikey} replace {purl} and {apikey} with the values for your institution because this example places the api key in the url, use it only for testing in a secure environment for integrations, use the authorization bearer {apikey} header where supported api reference this guide covers the general requirements and recommended practices for working with the ampeducator api for the complete technical reference, including available resources, methods, required parameters, return objects, and field definitions, see the ampeducator developer api reference https //ampeducator com/api php