Highmark is a healthcare delivery and financing network based in Pittsburgh, PA.
API Design, Development, Reuse and Visibility
Explorer, Mocking, Visual Design, and Documentation
Outdated Code-First approach slowing teams down
Like many big companies, Highmark has APIs in different stages. From legacy web services to newer RESTful APIs, each requires knowledge of the business problem. Yet, Highmark found itself working against an outdated SOA mindset. With too much focus on the technology itself, teams were coding before they even knew what they were building.
Teams were constantly hitting roadblocks because they didn’t have the information they needed. It was difficult to get the key business knowledge from the stakeholders in the organization. By the time they did get those stakeholders involved, they would often find their time and efforts were wasted as they had moved forward with poor insight on the business’ needs.
Collaborative Design-First approach to API Development
Highmark has used Stoplight to push a true API-first evolution throughout its organization. The team used a combination of the right people working together and rapid prototyping to get immediate feedback. The results have decreased delivery time and allowed Highmark to reimagine its digital capabilities.
To get such results in less than a year is a major accomplishment for any organization. In addition to enabling collaboration, Stoplight enables Highmark to easily define the elements of a good API through a visual editor, not requiring users to build designs in a text editor.
As a way to test its new, collaborative approach, Highmark set out to redesign an API to simplify the process of sharing members’ ID card information. To do so involves building a product with the following capabilities:
- Retrieve all ID cards
- Request an ID card
- Show the ID card on mobile devices
- Send the ID card's information to doctor's offices
A project like this does not happen without considering existing APIs and data. In reviewing the previous approach, Highmark discovered about 10 different ways to refer to a member’s last name. Inconsistency can slow down development teams, so Highmark worked with stakeholders to create data models that can be used across multiple APIs.
By using Stoplight, Highmark encourages reusability by exposing its design assets to all teams. This form of collaboration can happen even across teams that don’t work together directly. When teams design the API around existing models, they can create consistent designs instead of making changes after the design process.
Before design-first evolution, Highmark’s Marc Patterson was worried the API process could not keep up with the growing number of APIs powering the foundation of the business. One of two API architects, Patterson knew the benefits of API consistency could be joined by efficiency. However, progress was slow.
Patterson identified two things needed to increase their speed:
- The right people together at one time -- from frontend to backend and technical to non-technical.
- A way to make and see changes instantly.
Stoplight provided a way to get buy-in without going too far into development. Previously, business needs were translated over a span of weeks, now the process happens collaboratively, often in real-time. With Stoplight, stakeholders can see what was previously conceptual. Development teams move forward confident of the needed information and direction.
Highmark found that it’s not enough to be on the same page regarding the goals of an API. Often, you need to collaborate around the details of the API. Stoplight’s API design tools allow teams to see results and make edits. One example came as Highmark was focused on quickly getting a minimally viable API product produced. During a call, with the Stoplight editor shared on Patterson’s screen, the team realized they needed a course correction. They were viewing the ID card API response model and realized that they were including too much information in the payload. One of their goals was to be deliberate in the information provided. Their use case called for much less information, so they were able to trim down the model by making a subset of the full ID card response.
This was something that they were only able to realize due to the visualization aspects of Stoplight. Stoplight gives them a way to quickly see that response payload and come to the realization that it wasn't what they wanted.
Without visibility into the API at its earliest stages, the team would have noticed this issue when it was a much more difficult fix.
That example alludes to a common theme in API development: it’s hard for organizations to get full visibility into their APIs. There are so many moving parts being used and reused throughout one API—let alone hundreds or thousands. Your digital transformation requires a view of your design assets, so you can use them to collaborate amongst stakeholders. Follow Highmark’s lead to get the right people together to take part in the critical early stages of API development.
If you're ready to start your streamlined API development journey, create your workspace and see exactly what the Stoplight experience looks like.