I am working my way through the use cases on the Postman website, getting familiar with how their customers are using the platform. They have some very straightforward use cases that they have assembled based upon actual ways in which their customers are applying the value they bring to the table. Developer on-boarding is a particular fascinating one for me because it really touches on one of the most difficult aspects of APIs—getting someone new up to speed on what is going on. Getting people to go from zero to understanding what an API does and actually making API calls is how you begin to realize the value from new users, developers, employees, or anyone you are trying to reach with your API operations.
Postman has broken down the developer on-boarding use case into four easy to follow areas, breaking out some of the ways in which Postman is being used to get new users up to speed in a very hands on way, that really is the best way to learn an API in a way that will ensure it is much more sticky then just reading documentation. Their developer on-boarding use case provides what you need to quickly reach new users, and keep them engaged with the API lifecycle, allowing you to engage with developers who are actually contributing to the delivery of an API, or with consumers who will be putting it to use within their particular applications. Here are the core building blocks of how Postman is being used when it comes to developer on boarding—on both the provider and consumer side of things.
1. Understand the API - Making sense of internal or external APIs using the API browser environment.
- Explore the API - Being able to kick the tires and see what an APIs I all about, making sense of internal or external APIs.
- Import API Specification - Import a Swagger, OpenAPI, RAML and other specification and play with an existing API definition.
- Import a Postman Collection - Grabbing an existing collection and importing it to learn more about how an API works.
2. Build Use Cases - Taking collections and evolving them to meet the needs of specific use cases.
- Save API Calls with examples - Rounding off existing collection with examples making them more usable to developers.
- Write use case documentation - Publishing collections that are designed for specific use cases as usable documentation.
- Chain API Calls - Daisy chaining multiple APIs together to demonstrate how workflows can be delivered across multiple APIs.
3. Invite, Share, Or Publish - Inviting other team members or the public to participate and engage with collections.
- Invite Teammates to a workspace - Ask specific individuals on your team to participate within a specific API workspace.
- Share with another workspace - Take a collection you have build and publish to another workspace for engagement.
- Publish documentation - Publish API documentation from an existing collection, making available privately or publicly.
- Embed with the Run in Postman Button - Share a collection by publishing the Run in Postman button somewhere.
4. Collaborate and Improve - Work with others to improve upon the design of an API or specific collection.
- Get Feedback through conversation - Receive feedback from team members or trusted consumers using feedback solution.
I see developer on-baroding as one of the most important uses of Postman--more than just making an API request / response. This is the biggest pain point for API providers when it comes to getting new users to their APIs, and for organizations who are needing to on-board new developers with how APIs are being delivered across an organization. This represent the next generation of how you get up and running with any API, building upon the work we’e already done as a community to refine developer portals and API documentation to make them more usable by developers. This is how developers go from landing on a developer portal and browsing API documentation to actually using an API and understanding what it does in minutes, not hours or days. This is one of the ares you will hear me talking about regularly on the blog, and providing real world examples of the value an API actually delivers for developers, and what standards and best practices are in place when it comes to delivering APIs across an organization.
This use case is title “developer on boarding” — I am going to work hard to rebrand as simply “API on-boarding.”. Because I don’t believe that this is only for developers. This is a set of practices for on-boarding people to how to provide and consume APIs--because everyone should be both a provider and consumer—both developers and business users. I just wanted to work through this use case as part of my “on-boarding” phase with Postman as an employee. I am going to be working through hundreds of different stories and examples of how Postman can be used to on-barding individuals to the world of APIs, to how a company does (or doesn’t) do APIs, individual APIs, or workflows across many different APIs. Out of all of the Postman use cases this is the one I am most excited about and I feel will have the biggest impact when it comes to how APIs are used across companies, organizations, institutions, and government agencies.
