Earlier this year, I shared some background information about the beginning of the new Person API being developed by the Integration Platform Team. A lot has happened since then, including our team changing its name to the API Team. But more importantly, we are now at a point where the Person API is ready to be used at UW-Madison.
One of our goals for the Person API was to be able to publish documentation such that a technologist at the university could discover the API, be able to know whether it will satisfy their needs, and start the process to request access to it – all without needing out-of-band information or being “in the know” about the API’s existence. By building an API in this way, we allow potential users to answer many questions about the API themselves in a self-service fashion, without needing to schedule meetings or engage in lengthy email conversations. Our team is still available to answer any questions or jump on a call as needed.
Implemented as part of the Interoperability Initiative, we used the Developer Portal to contain all the documentation for the Person API as well as guide users through the process of registering their application and requesting access to the API. The main documentation for the Person API is the API specification, which describes the operations available to API users and the data returned by the API. A Mock Person API is also available, which contains the same features and returns data the same way the actual API does, but with fake data. A mock API allows someone to try using the API before requesting access to the real one, as well as start integrating their application with the API before they have access to real data. Once access is granted, the hostname can be changed to point to the API with real data.
We also made some guidelines on using the Person API, which contains recommendations and sets expectations for things like versioning, quotas, and our Service Level Objectives (SLOs) for availability of the API. SLOs allow us to define and be transparent about what it means for the Person API to be “available”. Availability is not measured based on whether an underlying server is running, because that’s an internal detail that might not have a direct effect on what matters to the users of the API. Instead, we defined our SLOs using response times and error rates, since those are metrics that have a direct impact on user happiness.
Although we are finished with our first release of the Person API, we are only at the beginning. We are continuing to make improvements to the API, add additional features, improve performance, and provide supplemental documentation – all based on the needs of the people who use the API, their use-cases, and the feedback that we get about the API.
To that end, one question we often get asked is “Will the Person API contain X data?”. The short answer is that it could, but let’s work together on your use-case to determine how the Person API could best solve it. We want to make sure that the Person API is solving real problems at the university, so we avoid adding data or features before we know they will be needed. If the current Person API does not satisfy your needs, please let us know and we can work together to identify your use-case and add work to our backlog based on your needs and priorities. New use-cases for person data will allow us to continue improving the Person API and make sure it’s solving a broad range of problems.
Lastly, I’d like to share our continued open invitation to our regular sprint reviews, where we demonstrate the work we’ve done over the past two weeks and gather feedback from stakeholders. Anyone is welcome to attend our sprint reviews, so feel free to reach out and we can add you to the invitation.
As a next step, I encourage people to look through the Person API documentation shared in this post, try using the Mock Person API, and when you’re ready, start the process for requesting access to the real API. If you have a new use-case you’d like to share, want to attend our sprint reviews, or have any other questions/feedback on the Person API or the Developer Portal, feel free to email our team: api@doit.wisc.edu
– Jared Kosanovic
Enterprise Integration – Technical Lead
Division of Information Technology