API Design Amplify Engage

How API linting improves your organization’s API design and governance

How API linting improves your organization’s API design and governance with Amplify Engage

When you consider that APIs are meant to be the fundamental building blocks of digitalization, it becomes obvious that scaling the API practice is critical. And this can become a real enterprise challenge once it has been decided that APIs should become an important strategic direction.

API linting can help achieve this because it allows you to check and enforce (some aspects of) API guidelines, making it easier for API teams to follow standards – and making it easier for API platform teams to make ensure the guidelines they have established are being followed.

In this blog, we’ll explain API linting, how it works, and how Axway’s Amplify Engage helps you automate validation and security for APIs your teams can trust.

What is API linting?

API linting is the process of making sure that APIs are not just technically correct (which is the realm of validation tooling), but that they also comply with a set of additional constraints that often are documented in the form of API guidelines.

Concretely, Axway’s Amplify platform performs API linting through the integration of Spectral an open-source API linting tool that allows users to write rules which then can be used to check API descriptions.

At its core, Spectral is very simple: you input an API description (OpenAPI, AsyncAPI, Swagger, …) and a set of rules, and then it checks whether the API description follows the rules.

This can help with automating API guidelines to some extent and depending on how much effort you put into it, you can check for rather basic things such as that every resource should have a description associated with it, or you can get more sophisticated to cover more of your API guidelines.

See also: The role of API standards in an enterprise strategy

How do API linting rulesets work?

Understanding the potential of API linting rulesets means understanding how they work and how to best leverage their capabilities. The rulesets are defined in Spectral and executed against the API definitions of the discovered services.

An easy start is to use out-of-the-box rulesets. Spectral comes with built-in rules that go beyond what the API specifications require. You then get the result of checking API descriptions per Spectral’s default rules, which can already catch some issues with API descriptions.

Beyond that, for more advanced insights, it makes sense to create custom rulesets based on API guidelines you can define for your organization. Using Spectral this way now allows you to specify additional rulesets that Spectral will use to check your API descriptions.

Additionally, one can use pre-defined or self-developed functions (implemented in JavaScript) in Spectral to create more advanced rulesets. These functions allow you to perform operations and will return success or failure results.

For greater detail, we dive much deeper into API linting with Spectral in this blog: discover 7 steps from using it as a simple out-of-the-box tool to one that can level up your API governance.

API linting ruleset examples – what standards make sense?

This has been a fairly abstract overview of API rulesets, so let’s look at examples of what those rulesets can do and what they can check.

An easy example of an API linting rulest would be to define a design rule that states that every API definition must contain an API description. This way, teams can make sure that the API description can later be reused and provided to consumers to help understand what capabilities the API provides.

Axway VP of Catalysts Brian Otten discusses how automating tasks like documentation, coding, and regulatory compliance checks for developers helps implement an API-as-a-Product strategy.

Another example of a design rule would be to check whether status codes are included in the API definition to make sure the API’s response gives meaningful error messages. This makes it easier to adopt the API call.

Security rulesets can be used to evaluate whether an API is suitably protected. An example would be to check whether the API is protected via OAuth or API key.

Should this check fail (for example, if the API is only using basic authentication), you can immediately recognize services that might allow attackers to gain access to protected backend applications.

For more examples, see how one transportation leader uses developer input to continuously improve API standards.

How does Amplify Engage help enforce API standards?

Two important aspects of most API strategies are to 1) allow for great autonomy of API teams and 2) use APIs to increase the velocity with which new capabilities can be delivered.

  • Autonomy can be increased through linting because the easier it is to check for compliance with API guidelines, the easier it becomes for teams to create and change APIs without having to be concerned about running into compliance issues later on.
  • Velocity can be increased thanks to linting because API reviews can be partly automated, meaning that issues can be caught earlier on and are easier to fix.

Leveraging the process of linting also means that the potential bottleneck of API reviews performed by an API platform teams can be managed in a more effective way, by using manual review processes only for those parts that cannot be automated.

Amplify Engage (formerly Enterprise Marketplace) serves as a single point of truth for all APIs an organization exposes. With the help of agents that automatically discover exposed APIs on various types of API gateways, it centralizes API governance.

This makes Engage the best place to start checking the API specifications for compliance with your organization’s design and security guidelines.

How to implement API linting in Amplify Engage

Once the discovery agents upload the specifications of the published services from the gateway, they are deployed onto your enterprise marketplace. Amplify Engage allows for implementation of rulesets that are automatically executed upon service discovery.

Users can define dedicated Spectral rulesets for different environments, or just use the same rulesets across the tool. This means that the moment the services are shown to the user in Amplify Engage, they will already show the results of the linting ruleset execution.

For more step-by-step details, see Axway documentation: Manage your compliance with Axway Central CLI

Every discovered service is given a grade from A (very compliant) to F (non-compliant) within the ruleset. This allows valuable insights to surface immediately.

The following clip from a recent demo of Amplify Engage shows how it automates validation and securing of APIs, while offering a single source of truth regarding your digital assets.

 

 

Watch the full 30-minute on-demand demo to harness your APIs through a seamless Marketplace.

Taking the score into consideration enables better decision-making about which services to publish to consumers and which services made need some more development to ensure compliance.

Furthermore, you get a view of security liabilities and can close potential backdoors into your enterprise’s IT landscape by investing more development capabilities in patching the services with the worst security rating.

Want to unify cross-team API governance and security? Learn how Amplify Engage can help.

Key Takeaways

  • API linting extends beyond basic validation by ensuring APIs comply with organizational guidelines and standards, helping scale API practices across the enterprise.
  • Through integration with Spectral in Amplify Engage, teams can automatically validate APIs against customizable rulesets for both design and security compliance upon discovery.
  • Amplify Engage's automated API linting capabilities increase team autonomy and development velocity by providing immediate compliance feedback and reducing manual review bottlenecks.