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.
"In one example, we were able to move from ideation to a complete Stoplight prototype in 6 hours. Before, it would usually take weeks and often wouldn't have the right people involved. Now we have a point of collaboration."
— Marc Patterson, API Architect at Highmark
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:
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:
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.
"Once we have an interface designed, we can have a prototype set up with just a few clicks. It's incredibly powerful to get to prototyping so quickly."
— Marc Patterson, API Architect at Highmark
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.