Design and Build API with Postman
25 Feb 2020
I am doing more talks and workshops within enterprise organizations educating teams about designing and building APIs, helping Postman customers be more successful in not just using Postman, but in defining, designing, delivering, supporting, and evolving high quality APIs using Postman. 90% of the teams I work with are still build-first when it comes to delivering API capabilities across the enterprise, so we are invested in helping bring that number down. Empowering teams to go API-first when it comes to designing and building their APIs, moving beyond the more costly approach of writing code first, and develop more healthy practices that involve business and technical stakeholders in the process.
It is natural for developers to want to roll up their sleeves and begin coding to deliver an API. It is what they are trained to do. However, it makes a lot more sense to involve business stakeholders earlier on in the process, and avoid the costly, isolating, and more time intensive approach of purely approach APIs a writing code. API has been working internally, and with our most engaged customers to better define what an API-first workflow involving the following stops along the API life cycle:
- APIs Builder - On the Postman platform, all APIs begin with the new APIs tab—the beta implementation of being able to manage the API life cycle within Postman.
- Create - You can create a new API by starting fresh, or importing an existing API definition in the OpenAPI, RAML, or GraphQL formats, and use it as the definition for each new API>
- Definition - To change the design of an API, you can directly edit the OpenAPI, RAML, or GraphQL definition, manipulating the design of the API and the underlying schema.
- Mock - With an API definition you can then mock each API, providing a virtualized representation of each path, with examples returned as mocked responses.
- Environment - Defining key / value pairs and globals that can be used to authenticate and establish context for each API, providing one or many different ways to use an API.
- Document - Publishing modern API documentation for the API, providing human readable documentation including paths, parameters, schema, examples, and code snippets.
- Test - Investing in test suites that allow each API to be automated, orchestrated, and validated that it is delivering as expected, based upon a set of known outcomes.
- Monitor - Scheduling the regular monitoring and execution of APIs, and API-driven workflows, ensuring that they are run on a regular basis and in response to particular events.
- Share - Make an API available within organized workspaces that are targeting specific teams, making it available as collections, complete with environments that make them usable.
- Collaborate - Invite teams to collaborate around the designing and building of APIs, allowing business and developer stakeholders to be part of the overall API life cycle.
This is intentionally an API life cycle that is inclusive to business stakeholders as well as developers. It is intentionally void of the bitter gritty technical details to make more accessible for business users, but also help developers consider the bigger picture. This is an API-first approach to designing and building APIs that can be then be developed and put to work in a production environment. This approach to delivering APIs centers on providing everything that is needed for business and technical stakeholders to work together to establish a complete definition of what each API should do, before it is actually realized by writing code or publishing to an API gateway. Providing an iterative workflow that can be repeated until all of the technical and business details of an API are well-defined, and approved by everyone involved.
Designing and building APIs isn’t something that developers and IT groups do in isolation anymore. This process represents the evolution of and maturity of modern API infrastructure, and not just providing APIs, but delivering consistent and reliable APIs that meet business objectives. Postman is widely known amongst developers for being a dead simple tool for putting APIs to work, but it is also becoming where you design and build APIs. Providing not just API client tooling, but as you can see from the list above, a whole suite of stops along a modern API life cycle that helps organizations take control over how APIs are delivered across their teams. Establishing a common set of practices for how API infrastructure can be defined, delivered, and evolved at enterprise scale.