Hari Krishnan - Leveraging API Specifications to test API Providers / Services
What is your experience with designing and building APIs?
I have been designing and building APIs for more than a 15 years. Over these years I have extensively worked on
- REST Http, SOAP, etc.
- Internal and Public facing APIs
- API auth and auth, metering and monetisation, testing, performance engineering and security
- API Specifications - OpenAPI, AsyncAPI, WSDL, etc.
I am currently exploring developments in areas such as Server Sent Events, GraphQL, API Specification Standards such as AsyncAPI, etc.
My recent work involves leveraging API Specifications such as OpenAPI, as executable contracts to eliminate integration testing through Contract Driven Development. I am a core contributor to an open source tool called Specmatic that embodies this approach.
While creating API Designs, implementing and / or consuming and testing them, what challenges have you faced / are facing?
Independent development and deployment of services - Having a good API boundary should allow independent development of API provider / service and consumer applications. However, without proper mechanisms to enforce the API boundaries, integration issues wreak havoc in the later stages of development. So many teams resort to sequential style (Provider before Consumer etc.) which is not productive and severely impacts time to market while shipping features.
Stale Stubs - It is common practise to standup a mock server to emulate an API in order to allow convenience of consumer application development. However such mocks often go out of sync with the actual implementation. This again leads to broken integration late in the cycle.
Testing Providers - Providers do not have any emulation of the Consumer in lower environments. The only way to actually test if Consumers are compatible with a Provider seems to be either through Integration Testing and / or End to End Testing. This is a major setback for teams that have been adopting microservices since it impacts their ability to deploy services independently. There is a necessity to be able to shift left the identification of compatibility issues and reduce / remove dependency on Integration Testing.
Communication and Collaboration - API Designs being communicated over textual / non standard / non machine readable documentation is / has been a major contributor to communication gaps between developers. Adopting machine readable specification standards such as OpenAPI is a welcome change. However there is a necessity to start treating these API Specifications as code in order to effectively collaborate over them.
Backward Compatibility - As APIs evolve as we add capabilities, testing for backward compatibility is both expensive and time consuming. Adding features becomes progressively more difficult as we have take into account all the possible impact areas.
What lessons have you learned with regards to designing and testing APIs?
API design cannot be an afterthought - Be it internal, backend for front end, public facing APIs, it is important in my opinion to begin with the API Design. This has several benefits such as fleshing out the use cases, reaching an agreement between stakeholders, etc. ahead of time. However this does not mean complete upfront design that is set in stone. Initial broad strokes design leaving room for API evolution has been definitely productive in my experience.
API Specifications as Code - I have been leveraging OpenAPI extensively and we treat API specs as code, meaning they reside in our version control. Changes go through a stringent pull request based process just like any other code. This allows for a single source of truth for all stakeholders (Designers, Architects, Developers, Testers, etc.).
API Specifications as Executable Contracts - It is important to enforce API Specifications so that both API Clients and Providers are adhering to the design that was jointly agreed upon. This needs to happen early in the development cycle to avoid integration issues later in the cycle.
API Design Patterns and Reuse - Patterns naturally merge within the context of each industry verticals and organisations. It is a good idea to remain consistent with an overall agreed pattern on how a certain feature behaves (Example: pagination, filtering, etc.). Capturing such patterns as reusable API Specification snippets reduces duplication and promotes consistency through reuse.
API Design Style and Smells - Linting API Specifications is a great way to reduce burden on API reviewers by codifying practices. This can also reduce design smells.
What do you plan to learn /explore at this conference?
At a high level, I would like to learn about how other participants have been tackling the integration testing hell with API boundaries and also their experience adopting specification standards such as OpenAPI. Below are some specific areas that I would like to explore
Should API specifications such as OpenAPI evolve to capture API behaviour in addition to capability. Example: OpenAPI 3.x allows us to describe all the possible response codes, however it does not have an inbuilt mechanism to document which request may trigger a certain response code. This means that for this part of the information, we need to either go back to looking at the API Tests, Workflow Tests or worse textual descriptions within the specification which is not verifiable / testable and hence has the risk of going stale.
Asynchronous APIs - Testing strategies and associated challenges
How do you plan to contribute?
I would like to have / facilitate a discussion around one or more of below areas
API Specifications as Executable Contracts - What it takes to enforce API Specifications during application development
Async API Testing Strategies and associated challenges in test data setup, testing environment, etc.
Capturing API behaviour in addition capabilities with OpenAPI extensions, overlays, or are there other techniques?
Call for Papers CLOSED
Ended on Oct 30 '22 11:59 PM IST
In our experience, having participants write a position paper before coming to the conference leads to better discussion because people have thought about what they want from the conference. Last thing we want is to spend half of the conference time figuring out what you want to figure out.
A Position Paper is a simple paragraph which answers the following questions:
- What's your experience with designing and building APIs?
- While creating API Designs, implementing and / or consuming and testing them, what challenges have you faced / are facing?
- What lessons have you learned with regards to designing and testing APIs?
- What do you plan to learn /explore at this conference?
- How do you plan to contribute?
* Note that the above questions are just pointers, you don't have to answer each one point by point.
