Using linting in IBM API Studio

Discover how to use linting to address issues in your code.

Linting helps maintain high-quality, consistent code by identifying issues such as missing fields, invalid values, or structural inconsistencies. In IBM API Studio, it ensures that API definitions, governance policies, and configurations meet predefined standards before reaching runtime or production.

By enforcing standardized structures and validating essential fields, linting checks for consistency, compliance, and correctness in IBM API Studio projects. It allows developers to streamline workflows, improve API governance, and proactively resolve issues, leading to smoother deployment processes.

What is linting?

Linting is a static analysis process that checks project files for structural and semantic issues before runtime. It helps identify common problems and enforce consistent standards across API definitions and configurations.

Linting in IBM API Studio highlights issues such as:

Missing or empty required fields
Incorrect formatting or data types
Broken references to specifications or policies

Linting issues appear as errors or warnings, depending on their severity.

Types of linting results

IBM API Studio categorizes linting results as follows:

Category	Description	Action required
Error	Critical issues that developers must fix to ensure proper functionality. These issues can prevent APIs from working as intended and block certain operations.	Required fix
Warning	Suggested improvements that enhance correctness and maintainability but do not block operations. These recommendations help developers follow best practices and improve code quality.	Optional fix

Where to view linting results

IBM API Studio displays linting issues in the Problems tab at the bottom of the screen.

Errors are shown with a red icon.
Warnings are shown with a yellow icon.

Each entry in the Problems tab includes:

A short description of the issue.
Line and column number.
The severity level (Error or Warning)

Clicking an issue from the list will:

Navigate to the relevant line in the editor.
Highlight the issue directly in the code.

Tip: Hovering over a highlighted issue in the editor displays a tooltip with detailed information.

How linting checks run

IBM API Studio runs linting automatically as you edit and save project files. You do not need to trigger it manually. Linting results update in real time in the Problems tab.

How to resolve linting issues

To fix linting issues:

Open the Problems tab at the bottom of the screen.
Review the list of errors and warnings.
Click any issue to navigate directly to the relevant line in the editor.
Hover over the highlighted code to view suggestions or details.
Make the required changes in the editor.
Save the file to refresh the linting results.

Example use cases

Use case 1: Resolving API Specification issues in API definition

This example demonstrates how IBM API Studio flags issues related to the api-spec field within an API definition and provides resolutions for proper validation and functionality.

Before linting

The API definition lacks a properly populated api-spec field, which causes validation issues. This field ensures that the API operates correctly and adheres to the defined specification.

Code before linting

kind: API
apiVersion: api.ibm.com\v1
metadata:
  name: # Missing name
  namespace: dev_cors
  version: 1.0
  tags:  # Missing tags
  type: REST
spec:
  api-spec:
    $path: # Missing api-spec reference
  policy-sequence:
    - $ref: dev:policyseq:1.0

Identified problems and resolutions

Problem. Metadata name does not exist (Ln 4, Col 7)

Problem category. Error

Explanation. The name field in the metadata is empty. The API must have a name.

Resolution. Make sure that the name field contains the name.
Problem. Tag does not exist (Ln 7, Col 7)

Problem category. Warning

Explanation. The tags field is missing. While not mandatory, it improves classification and filtering, helping developers manage and search API definitions more efficiently.

Resolution. Add tags with relevant classifications.
Problem. The api-spec must only contain the $path (Ln 11, Col 10)

Problem category. Error

Explanation. The api-spec field is empty. It must contain a valid $path reference pointing to the API specification file.

Resolution. Make sure that the api-spec field contains a correct path reference, indicating the file location or resource path.

Updated code with linting fixes

kind: API
apiVersion: api.ibm.com\v1
metadata:
  name: CORS_Project # Added name
  namespace: dev_cors
  version: 1.0
  tags:
    - CORS # Added tag
  type: REST
spec:
  api-spec:
    $path: api/petstore.yaml # Added a valid $path
  policy-sequence:
    - $ref: dev:policyseq:1.0

Including a valid $path reference in the api-spec field, along with essential metadata, makes sure that the API is properly defined and validated in API Studio.

Use case 2: Identifying and fixing issues in a transport policy

IBM API Studio analyzes policy definitions and highlights missing or incorrectly defined fields. Addressing these issues improves organization, readability, and usability.

Before linting

The protocol field is missing from the policy definition, making it incomplete and unusable.

Code before linting

kind: Transport
apiVersion: api.ibm.com\v1
metadata:
  name: transport
  namespace: dev_cors
  version: 
  tags:

spec:
  protocol:

Identified problems and resolutions

Problem. Metadata version does not exist (Ln 6, Col 10)

Problem category. Error

Explanation. The version field in the metadata is empty. The API must have a version.

Resolution. Make sure that the name field contains the name.
Problem. Tag does not exist (Ln 7, Col 7)

Problem category. Warning

Explanation. The tags field is missing. While not mandatory, it improves classification and filtering, helping developers manage and search API definitions more efficiently.

Resolution. Add tags with relevant classifications.
Problem. Protocol is missing (Ln 10, Col 11)

Problem category. Error

Explanation. The protocol field is defined but lacks a value. This field specifies the supported transport protocols, and without it, the policy remains invalid.

Resolution. Add valid transport protocols such as http and https.

Updated code with linting fixes

kind: Transport
apiVersion: api.ibm.com\v1
metadata:
  name: transport_protocol
  version: 1
  namespace: default  # Added namespace field
  tags:               
    - transport_protocol # Added tags field
spec:
  protocol:
    - http # Added missing protocol
    - https

Adding the missing protocol values, along with the necessary tags and version, makes sure that the transport policy is correctly defined and functional.