A presentation at WeTest Athens in in Athens, Greece by Christos Gkoros
Testing OpenAPI definitions for better and consistent APIS Christos Gkoros API Architect - Platform engineering All rights reserved by Postman Inc
Build APIs All rights reserved by Postman Inc Use APIs Collaborate
Inside Postman 1. API Design 2. Scale 3. Platform Engineering 4. OpenAPI 5. Spectral 6. Test examples
The Postman API
Why integrate with the Postman API ● Enhance Postman’s capabilities Providing users with the tools and resources to optimize. ● Embed Postman within other workflows Like established processes enhances productivity and streamlines development.
As an API Architect I study ● Why our users need the API ● What functionalities they seek beyond the core product ● How are they trying to do that
Common Use cases ● Automation Scaffolding of Postman resources ● Auditing Ensuring the Postman resources are as they should be ● Tool integration Developer Portals CI/CD Test-planning, Test analysis, Test reporting …
My goals for the Postman API 1. Simple and easy to use 2. Effective at its job 3. Increase its adoption and usage
API Design
Elements of a good design ● Descriptive names Names that are descriptive names and aligned with the API’s goals ● Rich Functionality User cans do easily what they need, like filtering with certain attributes. ● Flexible formats The format is flexible and it adapts well on changes over time ● Clear error messages Good experience especially during troubleshooting
API API testing API API testing API
Scale
API Gateway brings common 1. Authentication 2. Security 3. Throttling 4. Routing 5. ….
The Postman API needs to 1. Have a common Look and Feel 2. Be a unified product rather a mix of different endpoints
Recap - What do we need? ● Good API Design ● Consistency at scale ● Autonomy ● Fast delivery
Platform Engineering
Test examples
Contact information
Semantic Versioning
Resources are plural nouns
No resource nesting
Camel case parameters
Date Format
Collection must support pagination
Collections must support sorting
Parameters should have examples
No version in paths
Error format - Problem Details
Challenges ● Testing the tests Since the tests are configuration files we need actually writing tests for them again ● Some things are hard to test even with Spectral For example descriptive names, but AI could help with that ● Re-evaluating tests As our API Design Guidelines involve we have to constantly adapt and update our tests ● Design dept and breaking changes Some of the old endpoints are not compliant but we cannot change them as this wall cause errors in existing users.
Actions that you can do 1. Figure out the API Design style you need 2. Create Spectral rules to codify it 3. Find a point in the critical path in the delivery life cycle that compliance testing can be performed 4. Enforce the use of OpenAPI 5. Implement your compliance testing 6. Come meet me at the Postman booth for further discussion. Thank you
In this tutorial, I present how we test APIs described with the OpenAPI standard internally at Postman. We will cover the objectives of testing, which include ensuring correct structure, completeness, consistency, uniformity, style, and documentation. Additionally, we will explore the tool used for testing, Spectral, and where testing fits in our software delivery lifecycle. Furthermore, we will discuss the challenges we faced, such as testing the tests, scaling the number of tests, and scaling the number of engineering teams involved, and how we overcame them.
The following resources were mentioned during the presentation or are useful additional information.
for free. You
can too.