1 of 48

10x DevEx �Shift-Left API Governance = CycleTime/2

Naresh Jain�naresh@specmatic.io

2 of 48

Misconceptions about API Design, Tooling and Governance

3 of 48

4 of 48

How about �HTTP REST and OpenAPI’s DevEx?

Given how widely they are used,

we should expect great developer experience by now, right?

5 of 48

6 of 48

7 of 48

8 of 48

Seamless, easy, frictionless (drive autonomy and self-service)

9 of 48

Efficient, performant and reliable at scale

10 of 48

Shift-left (early feedback) and avoid late surprises

11 of 48

Safe-fail experimentation – key for learning & growing

12 of 48

Integrated & Unified (no context switching/jumping thru hoops)

13 of 48

Customizable and Extensible (plugin/extension architecture)

14 of 48

Observability for data-driven decision making

15 of 48

Time & space independence for creative problem solving

16 of 48

Trust, transparency and clear accountability

17 of 48

What could be a much better DevEx?

18 of 48

19 of 48

Contract Driven Development – In a nutshell

Consumer

Provider

API Design First

Shift Left all the way to Design

Reduced time-to-market due to Parallel Development

Enhanced DevEx with improved Collaboration

Resilient API Building Blocks

20 of 48

21 of 48

This is a common problem for anyone in the

microservices and micro-frontend hell-hole

22 of 48

23 of 48

23

24 of 48

24

25 of 48

Why are we finding these issues so late in the game?

Let’s understand what was happening?

26 of 48

Issues we discovered �(even though the team thought everything was under control)

Even though there is a CI step to generate and push the latest OAS file in dev portal, in some cases, it was out of sync
Even though OAS is generated from code using CodeGen, when we ran contract tests against the code, it would fail
Consumers would have done development using request/response pairs, hoping that they would get the service in dev env to test before the release, but often that would come very late and real testing would happen in SIT
Between design and development, as more knowledge and constraints are revealed, the API schema and design would evolve, but the same would not be captured and communicated explicitly to the Architect and Consumers
While updating existing APIs, the changes would break backward compatibility - but would only identify this during regression testing with an older version of the consumer
Test data management across 100s of systems was extremely difficult
External dependencies (payment gateways, service subscription integration) not available for testing
Perf testing and chaos testing in Staging env would surface issues with back-pressure (circuit breaker) or empty state and error state handling

27 of 48

28 of 48

Contract Testing using Pact

What did we discover…

29 of 48

30 of 48

Due to these mismatches & the steep learning curve

Pact did not work out for us

31 of 48

What is an API contract?

Based on this learning, what are the key attributes of an API Contract?

32 of 48

Our criteria for a viable API contract included:

Standards based; machine parse-able (OpenAPI, ASyncAPI, WSDL)
Tech stack and programming language agnostic
Friendly to all the stakeholders (Devs, SDETs/QAs, Architects)
Established ecosystem with a strong community
Something the team is already using at Design time

33 of 48

Hand-rolling mocks using request/response pairs is a bad idea

Wiremock (MockLab) to rescue

34 of 48

35 of 48

Wiremock - Challenges

You can feed spec incompatible examples, wiremock would happily serve them

there were no validation of examples to make sure your test data is spec compliant

Wiremock does not have any built-in checks to make sure the spec you have given it, is correct and the provider is adhering to it

36 of 48

API Provider

Contract Test the API provider using the same OpenAPI Spec that the API consumer is using with Wiremock

37 of 48

Dredd

Project was not seeing active updates at the time
Lack of support for OpenAPI 3
Very NPM heavy and difficult to easily integrate into the Java tech ecosystem

We also looked at a few other tools including ReadyAPI which did not support contract testing and was a paid tool.

38 of 48

Decided to build an inhouse tool with the following expectations…

39 of 48

Support specification standards like OpenAPI, WSDL, AsyncAPI

40 of 48

Same tool for service virtualization and contract testing��API Specifications as Executable Contracts

41 of 48

Collaborative at heart - forcing function for collaboration

42 of 48

No Code solution - language and tech stack agnostic

43 of 48

Great UX for Architects, Devs (Provider and Consumers), Testers

44 of 48

Independent development and deployment

45 of 48

CI native - runs everywhere from local to CI to test envs

46 of 48

Contract Driven Development – In a nutshell

Consumer

Provider

API Design First

Shift Left all the way to Design

Reduced time-to-market due to Parallel Development

Enhanced DevEx with improved Collaboration

Resilient API Building Blocks

47 of 48

https://insights.specmatic.io/

48 of 48

Hit me up!

naresh.jain@specmatic.io

https://linkedin.com/in/nareshjain/

nashjain

https://nareshjain.in