There are plenty of ways to think about and define API designs. I think of them, at their highest level, as communication between developers. And by improving API design, organizations reduce friction and improve relationships between individuals and teams — which makes their work life a little better.
Stoplight’s platform is designed to deliver high-quality features that improve the developer experience and customer outcomes. Here are four ways Stoplight delivers API tools that reduce friction and improve outcomes:
1. Efficiency Through Multi-Use Work Products
Every API is measured in terms of its usefulness — how many people use it and what technologies it connects to. While external APIs come to mind when we think about connectivity in this respect, this idea also holds true for internal APIs. This is especially true when you consider that the API’s design and formal description are the authoritative sources rather than its implementation.
Stoplight’s open-source tools empower creators to design, document, and build complete APIs. While the API is the goal for most customers, the documentation and descriptions that are created are extremely valuable and can be instrumental to concurrent branding and development efforts. For example, the OpenAPI specification we follow can be used to generate client code for web and mobile development. So once a company’s API designs are created, the same source materials can be used for websites and mobile apps, reducing redundant work and increasing design and branding consistency.
For example, Stoplight uses a variant of json-schema-to-typescript to generate TypeScript types that mirror our API spec’s request and response bodies. These types are the first building block of both our server-side implementation and the TypeScript client used by our web UI. Similar tools cater to other technology stacks, so there’s a good chance this technique can work for you whether your team uses Java, C#, Python, or some other language.
2. Contract Testing Through the Entire Development Cycle
My colleague Phil Sturgeon explains that API testing is “a software process which validates that an API is working as expected. Once declared, API tests can run automatically, such as part of a test suite on a continuous integration server, a development environment, or even done in production.” Our open-source tool, Prism, is great for this. You can also find it as a part of the Stoplight Platform experience.
Basically, it’s a verification process to make sure the API is being developed correctly and will work as intended — and the sooner you can begin testing your APIs, the better. Contract testing focuses on making sure different parallel development teams arrive at the same point when concurrently developing software. As Phil’s blog post explains, development disconnects between teams working on the same API are common; even when both parties are manually sharing the fields, types, and connections, their side of the code will need to work.
When there are oversights or incorrect assumptions, unnecessary delays can ensue as both sides backtrack and attempt to reconcile the development projects. Stoplight’s platform automates contract testing so all parties working on the same API initiative can at any point test their code to make sure it is consistent and will work with the other code being written simultaneously.
At Stoplight, we include contract testing whenever we run automated API tests — even in our local development environments. Our contract testing involves inserting a Prism proxy between our automated tests and the API under test. This approach helps us quickly and cheaply discover when what we’ve built doesn’t conform to our design long before a code review.
3. Consistency, Consistency, Consistency
Have you ever experienced the “ransom note effect” in an API? It’s what happens when chunks of unrelated and inconsistent code and coding conventions are lumped into the same API. It’s an annoyance for developers, who must try to make sense of the messy code, and it also poses major problems for the API’s end-users.
The first problem is financial in nature. Simply put, it’s expensive to code inefficiently. Messy code increases development costs dramatically, as the company pays for both the original coding and the time it takes for someone else to fix it. This drives up costs, which may be passed onto customers and will eventually make the development company less competitive.
End-users are also negatively impacted by inconsistent coding, as they typically encounter more friction and challenges in implementing the APIs. It goes without saying that this is a bad strategy for keeping your API customers happy and coming back with new projects.
Spectral rulesets can be your API style guide, enforcing rules automatically and incrementally as developers modify existing API operations or design new ones. You might implement rules such as “always use HTTPS,” “path segments must be kebab-case,” or “all APIs must include an operation with the /status path.” Our Style Guides series (Part 1 and Part 2) contains more ideas and details about getting started.
4. Increased Focus on Customers and End-Users
Companies with the most successful API programs have at least one thing in common: They think about the needs of their end-users from the onset of the development process until the API is released. We call this a design-first approach. Focusing on the user experience is a simple goal, but many companies lose their way as they navigate the twists and turns of the development process. Over the course of the development lifecycle, APIs can become developer-centric as developers lean in to fix and address the zillion little things that can go wrong when creating APIs without the support of a good toolset.
On the other hand, effective platforms like Stoplight automate so much of the work that it frees up time for developers to maintain their focus on customers. With documentation, governance, and design consistency all included in the platform; developers have more time to identify and think through all the nuances and details that contribute to a good, customer-centric API.
This level of focus on end-users results in better APIs that people will appreciate, adopt and recommend to others — which should be the primary goal for API developers.
Build APIs Easily and See Better Results
While I work for Stoplight now and have been a Stoplight customer for years, I have some experience making APIs the “old way,” mainly using informal tools such as whiteboards and Google Docs. Based on my experience, I can tell you with 100% certainty that no matter how good you are at coding APIs, Stoplight will make your life so much easier.
The level of fidelity and precision Stoplight makes it possible simply cannot be matched. Our platform helps you avoid so many small errors and downstream problems — it is absolutely worth your time to give it a try.
And the basic tool with everything you need to get started is free. Just give it a shot next time you need to implement or alter an API. You’ll learn something and save a ton of time, too.
