News · Apr 4, 2023
Introducing API Issues
This week we're releasing API Issues.
API Issues provide you with immediate targeted feedback when designing an API. They appear as a list of recommendations for you to implement in order to improve the quality, consistency and user experience of your API. Think of it as a spell checker for your API.
API Issues can be found under the new Issues tab in the Design view.
API Issues automate your style guide
When API products scale to multiple teams, a common challenge is ensuring that everyone designs and ships their portion of the API in a consistent way.
One approach organizations adopt is to publish an internal API Style Guide. The theory is that if common design decisions are codified in a central place, then teams will reference these patterns instead of re-inventing the wheel.
The problem with this approach is that teams still need to be made aware of the style guide, buy into it, internalize it and adapt their ways of working to incorporate the patterns into their product development process. For many teams with competing priorities this represents way too much friction. These teams also don't receive any feedback until they try to ship their API, at which point the style guide gets perceived as a bottleneck rather than an accelerant.
With API Issues, your style guide is no longer internal documentation but embedded into each team's process. This empowers all teams to adopt your API Style Guide immediately with little training or friction.
Go beyond linting
API Issues know about your API's use cases, which makes them incredibly powerful.
For example, Criteria knows when your POST request is used to create a new resource and will recommend that your API responds with a 201 Created status, or that your GET response returns a list of information as paginated data but is missing a next_page attribute.
A traditional linter would not pick up on these use cases in the first places let alone recommend any improvements.
Fix issues instantly
Traditional linters give you error reports. You still have to go back and fix them on your own.
API issues in Criteria can be fixed instantly with the click of a button.
Carrots, not sticks
While detecting, and even automatically fixing issues is good, not producing any issues in the first place is great.
Criteria leverages the built-in style guide so you can quickly create entirely new endpoints in seconds, with correct parameters, response formats and naming conventions.
Teams will adhere to your API style guide without even realizing it!
Not all API style guides are created equal. Popular open source ones include the Microsoft REST API Guidelines or Google's API design guide. If your organization doesn't have a style guide yet these are a great place to start. If you do have one we'd love to see it!