Person API Guidelines
The Person API is implemented using JSON:API and uses UTF-8 character encoding.
Authorize Each Application Separately
For the security of potentially sensitive information, each application using the Person API should be registered separately on the Developer Portal. This means that each application will have its own OAuth2 key and secret, which limits the potential disruption if a key needs to be revoked.
Limit To 1000 Requests Per Minute
Use of this API is limited to 1000 requests per minute per registered application. This is calculated on a rolling one-minute window based on when the request was received. If you've exceeded the quota, you'll get a response with error code 429: Too Many Requests. You may need to implement request throttling to avoid these errors.
If your use case requires more than 1000 requests per minute, contact the API team to discuss options: api@doit.wisc.edu
Implement Retries For Transient Errors
If you get a response with a 5xx error code, it may be a transient server error. These are rare, but are almost always fixed by retrying the original request. Your application should be made robust to this type of error by implementing a system for retrying requests that result in server errors.
You should not retry requests that return a 4xx error code. These indicate that there is something wrong with the original request (for example, querying a record that no longer exists) and will not be solved by retrying.
For more details and implementation suggestions, see the following articles:
Versioning and Breaking Changes
This API will grow and change in response to the needs of the UW developer community. The API team will make every effort to ensure that changes are backwards compatible.
If breaking changes are required, the API will be versioned with a new major version number, and the old version will continue to be available for a period of time. Older versions may be deprecated and eventually disabled, but the API team will alert any developers using the deprecated version and provide support for migrating to a newer version.
So far, all new changes and features to the Person API haven't required versioning the API.
Accommodate New Attributes
As this API grows, new endpoints and attributes may be added. Your applications should be capable of handling responses with new attributes in them. For example:
Old Response
{ "first_name": "Buckingham", "last_name": "Badger" }
New Response
{ "first_name": "Buckingham", "nickname": "Bucky", "last_name": "Badger"}
This would not be considered a breaking change.
Handle Changes in Data
The structure of the Person API, such as the names of attributes, their data types (e.g. string, number, boolean), and URLs, will remain constant to preserve backward compatibility. However, the content of the API is dynamic and will change with changes in upstream data sources. This includes large changes like the number of people in the Person API, but also changes to a Person's data such as the amount of items or objects in a list, or the length of a value of an individual attribute.
The logic behind computed values (e.g. the names in the root /people endpoint) can also change resulting in existing attributes being populated with new values from different sources.
To handle the dynamic nature of the data in the Person API, we suggest implementing these practices into your integration.
- When saving Person API data to a database with fixed column widths, use a generous maximum size (e.g. at least 1024 characters).
- If a value from the Person API exceeds the size of a column in your database, log and alert on the error, then adjust the column size as needed.
- Be careful with casting string fields in the Person API as numbers, since a string field could contain non-numeric characters in the future.
- Implement fault tolerance into your integration by logging errors but continuing with the rest of the integration. Depending on the specifics of your integration, when doing a bulk export from the Person API, log errors for people that fail to load in your database, but continue with loading the other people.
- Consume only the data that is needed for your integration. Use filters to get only the people that are needed and only consume the attributes/resources you need.
We discourage developing integrations with a tight-coupling with the Person API. For example, if an integration broke/failed when a new attribute was added to an existing endpoint, this would be a tightly coupled integration.
If your integration requires a tight-coupling with the Person API, you are responsible for being prepared for upcoming changes to the Person API to ensure your integration is ready. Please see the API Team's website for roadmap information to be prepared for upcoming changes to the Person API.
Usage Patterns
The Person API is intended to be used directly by applications on an as needed basis. This means that instead of using the API to update a local database, your application will send requests to the API as needed.
It's generally not recommended to use this API as a source for large ETL jobs or batch updates of other databases. If your integration or application requires person data be persisted in a local system or vended product (ex. SaaS), contact the API Team to discuss options: api@doit.wisc.edu
Percent Encode URLs
Make sure to percent encode (AKA URL encode) URLs when sending a request to the Person API. URLs returned by the API (e.g. pagination links) will be encoded. Most modern HTTP clients handle percent encoding by default.
Service Level Objectives
The following are the Service Level Objectives (SLO) for the Person API. These are the targets for several key metrics we will meet. If any of these fall below our targets they will be treated as high priority issues to resolve.
- Response times: 99% of GET requests will return within 1 second, and 99% of PATCH/POST/DELETE requests will return within 5 seconds.
- Error rate: 99.99% of requests will respond with a non-5XX response code.
- Data currency: Data in the Person API will reflect changes in our upstream system with 10 minutes.
Testing
The Person API is available in three versions: Production, mock, and test. The test environment sources data from the Integrated Test Environment (ITE). All versions have the same features and request/response structure. The main difference is in the data returned.
The mock Person API can help with becoming familiar with the API before requesting access to use it. It can also help to build a proof of concept integration using fake data.
For an integration that uses the Person API, non-production environments can use the mock Person API to help simulate real usage. If your application tests integrations in ITE, you can use the test Person API for your integration tests.
The production Person API can also be used in non-production environments, given that the data is being secured to the same degree that it would in the production environment.
For tests, such as automated unit tests which run scenarios that would normally call the Person API in a production environment, we recommend against calling the Person API. Instead, simulate a Person API response in your tests without calling the API. This practice is called mocking (not to be confused with the mock Person API).
By mocking test dependencies, tests become more predictable and faster to execute. For example, a change in data in the Person API could cause the same request to return a different response, introducing variability into the tests that would otherwise have no effect if the API response was mocked.
For integrations that consume Person API webhooks, it's also important to mock a webhook in unit tests of an integration. Instead of depending on the Person API to send a webhook at the right time during a test, have a way to trigger the part of the integration that consumes webhooks with a fake payload. This can be done by sending a fake payload via HTTP, or if possible, calling the function directly that would consume the webhook (i.e. isolating the HTTP receiver part of the integration for a more predictable test).
For more information on mocking in testing, see this article .