Testing OpenAPI definitions for better and consistent APIs

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