How to Bring Design-First APIs to Your Organization

Many organizations want more consistency and reliability within their API programs. They also want to streamline and speed up the API design and development process. Achieving these goals requires a repeatable, scalable process. In essence, it requires a design-first approach to building APIs where you:

• Determine Your API Guidelines and Development Process
• Collaborate Around API Design Documents
• Automate Some of the API Design Review Process

Determine Your API Guidelines and Development Process

You probably have architects and developers that support your API initiatives. And they may have already figured out an ideal process to build APIs.

However, are those teams building design-first APIs? Is every team following the same API guidelines and development process? If not, then you’re likely seeing your teams build inconsistent APIs and, ultimately, a program that doesn’t meet your expectations.

Without company-wide API guidelines and a development process everyone follows, you often end up with a “black box” process where API architects become the bottleneck.

Beware the “Black Box”

Large companies often run into the “black box” problem, where many teams develop APIs in silos and each step of the API development process involves a lot of back-and-forth communication. A siloed development process leads to teams taking a “guess and check” approach to API design and longer delivery times for every API.

Global energy management leader Schneider Electric found the black-box approach increased its time to market. The company was able to eliminate several iterations through a focus on transparency and reusability. There is now a defined process that the team follows for every new API project. In addition, API guidelines are shared company-wide. What previously were multiple reactive correction sessions now only require a single half-hour meeting with the proper stakeholders. No more guess-and-check API design.

To eliminate the black-box approach and speed up development, you need to share API design guidelines across your entire organization. You also need to document API design best practices, making sure that everyone involved in your API program understands and follows them.

Design API Design Best Practices

If you want everyone involved in your API program to follow API design best practices, then you need to identify them, document them, and share them with every team.

What are the API design best practices?

We could write a book on this topic (there is so much to know!) Here are a few best practices you should follow when designing APIs:

Create a Rock-Solid API Contract

Once you’ve chosen an API specification (we recommend OpenAPI), you should create an API contract.

At its core, it tells users what the API does. The contract should be available in both human and machine-readable formats. Committing to API contracts will help ensure the success of your API program. You can use API contracts to generate usable code and contract test APIs.

Reuse API Design Elements

You can use an API specification to define reusable components and reuse object definitions when building new APIs. And with Stoplight, you can create a design library, a place where teams can publish individual models and other design components. Teams can save time and ensure consistency across all APIs by reusing API design components.

Create an API Style Guide

Standardization is the key to consistency across your APIs. Creating a style guide that every team follows will ensure you build consistent APIs. You can create a style guide that covers nearly every aspect of an API. For example, you could set rules for API:

• Security
  • Never use “HTTP Basic,” always use HTTPS.
  • Every endpoint must include security in the form of OAuth.
• Errors
  • Standardize error formats across APIs.
• Versioning
  • Set rules for API versioning, such as version numbering for each API.

You can include rules about other API components, such as filtering, naming conventions, and pagination. An open-source JSON/YAML Linter like Spectral helps you create style guides easily.

Once you’ve determined and documented your API design guidelines and best practices, you should collaborate around your API materials.

Collaborate Around API Design Documents

You need to bring the right people together to build consistent and reliable APIs. And that doesn’t mean only highly-skilled technical people. Successful API programs involve people with different skill sets—those who design and build the APIs and those who understand the business problems the APIs are meant to solve.

API design is a technical endeavor, but not everyone in the process knows how to code or has a technical background. You can help bridge the communication gap between technical and non-technical stakeholders by collaborating around design documents, specifically through visualizing your API designs and using OpenAPI as a focal point.

Visualize Your API Designs

One of the best ways to communicate technical information to non-technical people is through visualization. Most non-technical people will have a hard time understanding API design through a text editor. But a visual editor allows them to participate in the design process and provide meaningful feedback. They don’t have to know how to code; they can use a simple point-and-click interface.

Take a look at our Highmark case study. Thanks to Stoplight’s visual editor, Highmark’s teams realized early in the design process that the “ID card API response model” included too much information. Without the visualization, they wouldn’t have seen this problem until much later in the design process, making it more difficult to fix. By looking at the actual API design, every technical and non-technical stakeholder better understood the solution before any code was written.

Use OpenAPI as a Focal Point for Collaboration

You can use the OpenAPI specification to visualize your API designs. You can also use OpenAPI as a focal point for collaboration among all team members.

For example, the teams at Transact use OpenAPI to:

• Guide team discussions around API design
• Store API designs within OpenAPI documents
• Import existing artifacts, ensuring all APIs remain consistent

Visualizing API designs and using OpenAPI as a focal point can help improve collaboration among teams. Another way to make collaboration easier among teams is to automate some of the API design review process.

Automate the API Design Review Process

When you use a design-first approach to creating APIs, you can get feedback on the design from stakeholders before a single line of code is written. And automating some of the review process can save time for everyone. One of the best ways to speed up design review is to implement automatic linting.

Implement Automatic Linting

You can enforce API design rules across all your APIs automatically by linting your API descriptions during the design process. With Spectral, a built-in feature of Stoplight, you can set up automatic linting and validation warnings.

Linting rules will save you time, and we have two great case studies that demonstrate that: Telus and Schneider Electric. Both companies use Stoplight’s linting capabilities to automatically check rulesets and save time during API reviews.

Design First. Build Better. When it comes to bringing design-first APIs to your organization, we’ve only scratched the surface. But you can dive into designing consistent and reliable APIs by trying our API design tools.