Shift Left Strategy for API Standardization

There was a rising development among the many organizations API group to raised standardize their API design and growth course of. With an elevated adoption in the direction of micro providers, software program merchandise being increasingly more only a bunch of micro-services and third-party APIs mashed collectively.So, it will get extra essential for us to get API construction so as utilizing the de facto customary like OpenAPI (a.ka. Swagger). To attain this consistency organizations have began to outline their very own pointers for standardizing their API. 

What’s API standardization

API design is the creation of an efficient interface that means that you can higher keep and implement the API, whereas enabling shoppers to simply use this API.

Constant API design means, standardizing the design, throughout all APIs, and the assets they expose, inside a company or group. It’s a widespread blueprint for builders, architects and technical writers to observe, to make sure a constant model and expertise within the API consumption. Organizations standardize design utilizing Type Tips that goal to make sure consistency in the way in which APIs are designed and applied. Some common fashion pointers are shared beneath.

1. Microsoft REST API Tips
2. Google API Design Information

I usually consult with this stylebook for creating a constant API for my aspect initiatives whereas following the business greatest practices for API growth.

Why Standardization

A transparent design methodology ensures that APIs align with the enterprise wants. With extra standardized API, there’s much less ambiguity, there’s extra collaboration, high quality is extra ensured, and API adoption will increase.

Having clear and constant API design requirements is the inspiration for a very good developer and shopper expertise. They let builders and shoppers perceive your APIs in a quick and efficient method, reduces the educational curve, and allows them to construct to a set of pointers.

API standardization can even enhance group collaboration, present the guiding ideas to scale back inaccuracies, delays, and contribute to a discount in total growth prices. Requirements are so vital to the success of an API technique that many know-how firms – like Microsoft, Google, and IBM in addition to business group like SWIFT, TMForum and IATA use and help the OpenAPI Specification (OAS) as their foundational customary for outlining RESTful APIs.

With out standardization, particular person builders are free to make subjective selections throughout design. Whereas creativity is one thing to encourage it rapidly can turn into chaos when not appropriately ruled by a method information.

Organizations can’t guarantee high quality inside their API design and supply course of with out standardization. Reinforcing design requirements improves the flexibility to foretell profitable outcomes and contributes to a company’s potential to scale their API growth at pace whereas guaranteeing high quality.

Journey into API standardization

It wouldn’t be potential to scale your API design and growth processes efficiently, or adjust to regulatory and business requirements, and not using a formal course of to strengthen standardization. Having an API design fashion information supplies the “guardrails” wanted to let inner and exterior groups collaborate when constructing API definitions and re-using belongings.

Initially, organizations begin publishing their API pointers internally as PDF or wiki for everybody to reference and processes are put in place to ensure groups are following the design pointers.One answer to develop consistency is offering a handbook overview throughout the API growth. 

The API’s are laid out in OpenAPI format and maintained in model management, we will observe the identical overview course of for API definitions that we observe for different code artifact. Builders can create pull requests for his or her API adjustments and have a colleague present suggestions.This handbook course of could be an efficient approach to make sure governance and compliance with the API guideline, however like all handbook processes it’s topic to human error and never all the time well timed.

Ready for a colleague to overview our API change may end up in a gradual turnaround that hurts developer productiveness, particularly on the subject of facets of the overview course of that may be automated. This course of can be not scalable when group scales and extra builders begin to develop API. That is the place shifting left with automated API evaluations is useful. It’s all the time higher to get suggestions early with the assistance of some automated instruments or linters like we do get for our different artifacts. 

What’s Shift Left method

The time period “shift left” refers to a apply in software program growth by which groups start testing sooner than ever earlier than and assist them to give attention to high quality, work on downside prevention as a substitute of detection. The aim is to extend high quality, shorten lengthy take a look at cycles and scale back the potential of disagreeable surprises on the finish of the event cycle—or, worse, in manufacturing.

Open API validators

On the subject of OpenAPI linters, I got here throughout a number of linters. These linters convert the API fashion pointers right into a algorithm and validate in opposition to the Open API specification. These linters can present you an possibility for customizing the principles as per your group fashion information. One instrument which caught my consideration was linter referred to as Zally which was written utilizing Kotlin and open sourced by Zalando. OpenAPI fashion information validators workflow seems to be like beneath.

1. The API customary or fashion pointers are expressed as a algorithm. Zalando has one such guideline right here.
2. API Written in keeping with OpenAPI specification
3. Linting instruments akin to Zally, sonarQube, Spectral that may validate that the OpenAPI specification the developer has written is complying with the specification’s guidelines outlined in step 1.

What’s Zally

Zally is a minimalistic and straightforward to make use of API-linter. Its customary configuration will examine your APIs in opposition to the principles outlined in Zalando’s RESTful Tips, however anybody can use it out-of-the-box. It’s written in a extra extensible method to permit us so as to add our personal algorithm as nicely. It additionally supplies the next function.

• allow/disable guidelines on the server aspect based mostly in your wants
• Accepts each json and yaml format for Swagger V2 and OpenAPI V3 specification
• Write and plug your personal guidelines
• Intuitive Net UI that exhibits applied guidelines and results of your spec validation
• Github integration utilizing net hooks which validates your OpenAPI on every pull request and echo again the violation within the feedback

Motivation behind Zally Gradle plugin

Although Zally is written in a extra extensible and customizable approach, I felt that we will nonetheless enhance zally present validation workflow additional to scale back the developer suggestions loop. Since Zally lacks the plugins like checkstyle, ktlint, spot bug and so on,. Under are a number of ache factors I skilled once I used Zally. 

• Builders have to host the Zally server both domestically or in a distant system to make use of the CLI instrument.
• Builders want to modify context for operating CLI instruments or some further work wanted to configure the CLI execution as a part of the maven/gradle construct course of with prerequisite of level 1. 
• Utilizing github integration elements to validate our API for every pull request will increase the suggestions loop time.

All these choices are rising the suggestions time for the builders with some handbook overhead of internet hosting the Zally server. So I made a decision to put in writing my very own gradle plugin which could be built-in within the native growth setting in addition to within the CI instrument which helps me to validate and extract the validation end in totally different codecs. .

Customized Zally plugin

zally-gradle-plugin is a gradle plugin which is written in kotlin and could be built-in within the construct script. The plugin validates the specification in opposition to the algorithm and supplies the report in each json and html format.

The venture consists of an instance job configuration:

```
// settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenLocal()
    }
}

// construct.gradke.kts
plugins {
    id("io.github.thiyagu06") model "1.0.2-dev"
}

zallyLint {
    inputSpec = File("${projectDir}/docs/petstore-spec.yml")
    reviews {
        json {
            enabled = true
            vacation spot = File("${rootDir}/zally/violation.json")
        }
        guidelines {
            should {
               max = 10
            }
        }
    }
}

//execute job
./gradlew clear zallyLint

```
```
Run ZallyLint job
./gradlew zallyLint
```

With this gradle plugin I’m in a position to get actual time suggestions throughout API growth. This allows me to repair points with the API earlier than getting right into a handbook overview step. The plugin can be built-in with the CI jobs to examine to validate the fashion pointers. As a result of all growth groups use the identical guidelines, the group can present a extra constant API for his or her customers. The advantages of the method are outlined beneath.

The plugin supplies an choice to allow exporting violation reviews into JSON and HTML format. This additionally supplies a straightforward method to configure guidelines to outline the max variety of violations allowed within the spec for every severity stage.

The json format could be parsed and exported into any database to calculate the API design compatibility rating and construct a dashboard to share it to the broader group for determination making on the API standardization initiatives. The identical approach HTML reviews could be exported to S3 bucket or google cloud storage and hosted as a web site to a broader viewers.