The Integration Platform Team within DoIT has started working on a Person API to help improve data integrations that use common person data, such as name and email. In this post, I’ll share the motivation behind the Person API, how we’re approaching the work, and why we’re using an API.
When we discuss an API (Application Programming Interface), we’re referring to an interface for interacting with data that aligns with the standards of the web (e.g. HyperText Transfer Protocol – HTTP). Similar to how a web user interface allows a human to interact with an application, an API allows an application to interact with other applications. An API can be thought of like a technical contract, defining all the aspects and expectations of its usage so that people who create applications know how to interact with it. Here are some common criteria defined by an API:
- Resources available in the API. For example, “people” is a resource in the Person API. Interacting with an API resource uses the same convention as accessing a normal website in a web browser, for example: https://api.example.com/people
- Operations available for each resource, such as whether the resource is read-only, or if resources can also be created and updated.
- The structure of the request and response payloads, including attribute names and value types (text, number, etc.), as well as descriptions for each attribute.
- Additional parameters that can be added to a request, such as for filtering or sorting data.
- Any quotas or limitations for the API, such as how often it can be used (e.g. 500 requests per minute).
- The kinds of errors that would be returned for invalid requests.
APIs are a common mechanism for interacting with data. For example, Uber uses the Google Maps API to help show where a driver is, and Google uses APIs from airline companies to search for flights. Private companies provide APIs as another revenue stream, but in a university setting, APIs provide other benefits:
- Reusability: A single API can be reused many times to fit different use cases.
- Simplify: APIs abstract a lot of the underlying details of an application so that someone doesn’t need to be an expert in a particular application to be able to understand its API.
- Robustness: Because APIs abstract a lot of underlying detail, they are able to remain more stable while underlying application can change behind the scenes. A good API allows applications to be able to change and adapt without needing to coordinate with one another.
To create a backlog of work for the Person API, we interviewed technologists across the university to understand their needs and current pain points with consuming person data. Creating the Person API based on these use cases will make sure we are always on track with working towards a tangible goal that solves a real problem. At the same time, we are also taking into consideration the reusable aspect of APIs, and making sure the Person API will be able to enable new integrations with person data that weren’t part of the initial interview process.
After interviewing future users of the Person API, we started designing the API and implementing a mock API. Designing an API first, also known as Contract First Development, allows us to get fast feedback from users to make sure the Person API will be able to meet their needs. We are using a specification called JSON:API as the base for the Person API. JSON:API defines the structure of an API such as request and response payloads, sorting, filtering, and linking resources to other resources. By using a detailed specification like JSON:API, our team can spend less time with the generic design aspects of an API, and focus more on the data that our users need to interact with. JSON:API also has many client implementations, making it easier for users to start integrating the Person API into their application.
Additionally, we implemented a mock API that acts like the actual API will, but with fake data. Besides the fake data, the mock API will provide the same capabilities as the real API so that users are able to start integrating their application with the Person API before we have released our first iteration. A mock API will provide benefits beyond this initial implementation phase. Prospective Person API users will immediately be able to try out the mock Person API to make sure it will meet their needs before going through the process to get access to real data.
We are also using this effort to improve the process for getting access to person data, starting with the Person API. Historically, access to person data has been granted based on the individual integration that needed the data, and which fields that integration needed. To make the process for getting access easier, while still aligning with expectations of the Office of Data Management and Analytics Services (ODMAS) and DoIT Cybersecurity, we are looking into a process that could approve access to the Person API based on the data classifications needed by the application consuming the data.
We’ll continue to share periodic updates on the Person API as work progresses. In the meantime, people can look at the initial design for the Person API and start using the mock API which is available through the Developer Portal. For more frequent updates on the Person API, anyone is welcome to attend our bi-weekly sprint reviews. If you want to participate in sprint reviews, have a use case for the Person API, or have any questions or feedback, feel free to contact our team: integration-platform@doit.wisc.edu
– Jared Kosanovic
Enterprise Integration – Technical Lead
Division of Information Technology