Revolutionizing API development: Collaborative workflows with Postman

Ah good afternoon everyone. I hope everyone's enjoying the show. My name is MC Reed. I am a Sales Engineer with Postman based out of Atlanta. I'm joined today by Brian Cross who will be providing our demo after my brief talk.

So over the past two years, there's been a tremendous explosion of APIs. Uh Jeff Bezos famously said back in 2008, if if you don't have an API, I can't see you now. He was just referring to his own company to Amazon at the time. But the idea was for all of the APIs across the organization that they wanted to bring to bear as a part of a customer facing product. The way to do that was to actually provide an API rather than traditional flat file services.

So what's happened since then? That was about the time that we had the explosion of the cloud. Uh we needed accessibility APIs to those clouds. We needed to do automation of the services on those clouds. And that revolution made software accessible to all companies rather than just to the traditional technology companies that were out there.

We also had containerization as well as the explosion of hybrid clouds so that you could able enable bursting mode precisely what the uh the retailers are doing right now. For the holiday season, they need expanded infrastructure. They go ahead and add additional cloud infrastructure to the to the uh traditional infrastructure and then they can dial that back down later.

And then we also had mobility. So we took all of this API access that was out there and we drove it directly into the hands of us to the consumer. So with the cloud, every technology company, excuse me, every company was finally available to become a technology company. API services were now accessible to all. And every company, every company even my banking app, for example, uh I can go in my, my, my my mobile device is accessing APIs to hit those back end services.

I've got my credit score available from a third party company. I can transfer money via Zelle to another account that I own using. Yet another API. What that means is that now in order to provide best of breed services, companies have had to evolve into technology companies themselves. They've been able to do that because they don't have to have all of the traditional engineering resources of a traditional technology company that's been outsourced to the cloud.

But it also means that in order for them to not just remain competitive but to be viable at all, they must adopt an API strategy, they must be able to wield those in house. So this explosion of APIs has literally happened over the past couple of decades.

Now, what's happening inside of these nontraditional technology companies, they have a traditional dev qa release cycle that they need to now manage. They need to know how to negotiate that. And now not just traditional software, but the API itself needs to be negotiated through this process. Again, for companies who haven't traditionally been technology companies, they also have diversified their stakeholders.

So in addition to dev qa ops, we now have API architects, we have uh compliance, we have centers of excellence security. If I'm in retail, I'm not worried about PCI. If I'm in health care, I'm now, I'm, I'm not worried about PHI and then we have uh additional stakeholders inside of the company such as uh such as support, such as the end user.

All of this requires that these groups and these stakeholders be talking to each other. It requires that they collaborate and it's not enough to collaborate around an individual API or naked APIs. They need a standard, globally accessible single source of truth that they can corral around.

We have, we had SOAP, now we have REST APIs GraphQL, we have a lot of the messaging protocols that are out there and we need a technology that can rapidly change, keep abreast of the changes in the industry. So that we can partner with our users in order to leverage those technologies to their benefit.

This creates API chaos. It creates complexity, especially at scale. It means that we need to be able to leverage best of breed services. We need to be able to leverage industry best practices in terms of technology. It means that we have time to market concerns because we're trying to get to market with our API our competitors are trying to do the same. They're trying to win one up us by working with partner companies to leverage their, their APIs so that they can deliver best of breed services through their channel.

And despite all of that technology may or may not be your core business, I was talking a moment ago about that single source of truth that we can all refer to in Postman. We call that the collection, not just one API, but a collection of APIs collection of APIs where we can describe what type of testing we need to do in order to def uh verify and express that an API is working correctly.

Not only that developers may have one way of verifying that an API works correctly. QA may have another operations, may have another. And if we are able to take the collection itself and move that through your traditional CI/CD process, it means that developers can do precisely that and then QA can leverage the testing that the developers made, they can add their own testing.

When we get to the center of excellence or when we get to the security team, they can leverage all the other tests that dev and QA made and they can add their own. It also means that we can ramp up the types of testing that we do using a technology called mock servers. It's the ability to take the definition of an API and serve a standard response rather than actually calling an API implementation.

What does that allow you to do? Well, if your third party API costs, you probably don't want to call it when you're just testing. It also means that when you put things like API specifications into place essentially in API spec if you design your API, before you start to code it, well, now my API implement and my API consumers, the people who are calling my APIs, they can do their work at the same time using that mock server.

What we're able to do is organize into communities of people who can share APIs amongst themselves. They can see fit to take this information, they can decide that they have some sort of problem and they can connect with another group, maybe inside the same company, maybe in another company who has a solution to that problem.

Now, you can be seen going back to Jeff Bezos words by easily leveraging a platform that's going to connect everyone so that they can easily literally within seconds have a problem and find the solution that they need. What we're able to do is take the traditional technology workflows that exist inside of our company. We're able to elevate APIs to be a first tier consideration in that traditional CI/CD workflow. And then what we're gonna do is take that API chaos and eliminate it.

Yeah. All right. Thank you so much MC. So let's take a step back and talk about how we wound up in this situation where millions of developers are using Postman on their desktops every day. So I think we all kind of came to it in much the same way. We all kind of came to Postman in much the same way. We needed a better way to learn about APIs. Fundamentally APIs are hard, they're hard to work with. There's no GUI documentation is sparse and often out of date, we needed a better tool and it turned out that exponential learning was far more effective.

So we all know we can come into Postman. Uh we can quickly create a request, enter a url for an endpoint, maybe change our HTTP method. Fire that off and immediately we are interacting with the output of this uh API and I can iterate on this quickly. I can add a parameter if that's something I want to do. Fire that off. Take a look at how that changes the behavior of the API I can even for this POST request, quickly add a body uh and fire that off and again, interact with the data.

So the takeaway here is that exponential learning with an API is just far more effective result, 30 million people using Postman every day. And from there, it's a pretty easy step to start collecting all of these requests, saving them into Postman collections, which are nothing more than exactly what they sound like kind of a treasure box or a toolbox of useful requests that we can go back to at any time and execute.

Um and this is great. This is my own little hoard of valuable uh API information, but things get complicated when MC finds out about my cool collection that does the thing and he wants to get his hands on it. So what we have to do at this point uh for most Postman users on the desktop is a really primitive process.

I have to export this collection to my local file system in JSON. And then I have to find some mechanism for getting this over to MC. Typically email, maybe Google Drive here. I am, you know, trying to figure out where this uh collection is because I've been doing this for weeks and months now. Hopefully it's this one. I don't know, we'll see.

So I'm going to go ahead and do that and fire that off to MC and that's certainly better than nothing. But now MC has a point in time copy of this collection, ah which means that if he makes any changes and wants to send those back to me, or if I update my API and I want to get him the updated version, we are manually merging raw JSON and that's very unpleasant.

So what this does essentially is stifle collaboration and creates thousands of islands where everybody has very valuable tools in these collections that they cannot share and nobody else can even discover exists. But there is a better way. Uh and spoiler alert, you'll never have to export a collection again.

So what we're gonna do now is we're going to shift over to uh Postman Enterprise and we're going to uh actually access one of those workspaces that MC was talking about. Uh and I'm gonna take on the persona of a developer working on an API.

So this is a workspace and fundamentally it's API resources and then the tools like environments and mock servers that MC was talking about that help you to work uh on those API resources.

So uh I'm about to uh hand this off to QA. Um and in the olden days, the way that I would have to do that again is go through that really ugly manual export process and QA teams struggle to stay in sync with developers. However, in Postman Enterprise, we're all in a single team. So what I can do now is simply click on the invite button and then in a single operation, I can invite in all of my QA engineers and give them the edit capability that they need in order to create the tests to complete the test cycle for this API.

So uh once I've invited them, they'll get a notification. We're gonna frame shift now and I'm going to adopt that QA tester persona. And my job now is to start writing the functional tests for this API.

So the first thing I'm gonna do maybe is something simple. I'm gonna use one of these preconfigured test macros over here on the right after I take a look at how the API actually functions. Uh and maybe I just want to ensure that I'm getting a 200 back, right? The most basic of functional tests.

I'm gonna go ahead and do that. I'm gonna send that request again. And now Postman is going to give me a very easy to understand visual representation of the state of those assertions.

Um of course, functional testing goes far beyond that. So let me just go ahead and uh quickly insert a whole bunch more functional tests and we'll go through a few examples of uh of what you can do here. So obviously you can check the return code, but you can also do things like examine the performance. What is our performance? Is it within spec are we getting back an actual uh valid JSON object and not an array?

And I can even include a snippet of our API schema and then use that to validate that the response that this API is delivering conforms to the contract in the design. All right. So I got a whole bunch more tests in here. I'm gonna send that again and now I've got five assertions uh in my test.

So, uh it looks like we are having an issue with response time. So how do I make my developer aware of that? How do we have a conversation around that again in the old days? All about email, Slack and meetings. Now, all I have to do is click on comment mode up in the uh upper right hand corner. There we go. Click on comment mode in the upper right hand corner, select the test that I uh want to draw his attention to.

I can actually call him out by name so that he'll get a notification. Uh and then ask, hey, what's going on with this? We got to get this down to 200 microseconds. Isaac's gonna get a notification which he can click on and uh come right in. In the meantime, I can leave a comment at the top level about the entire API uh project manager. Take a look at these tests, make sure that we're on schedule.

So now what we are having is interactive conversations inside a Postman. So Isaac gets that notification, he clicks on the comment, takes him right to the point that I want him to pay attention to. Uh and then he's gonna type of course a typical developer response after calling me out. So I know he's talking to me and tell me that it works fine on his machine, right? Of course, it does. Here is the remaining transcript formatted:

So the takeaway here is that we are now collaborating inside of Postman. We are not frame shifting, we are not context shifting. We're truly able to work together and think about this in contrast to just a few minutes ago, when I had to export this collection and then call MC on my phone uh to let him know that I'd done that almost impossible to collaborate.

Now, this value was unlocked across the entire enterprise and we can even resolve these comments. So it's like a lightweight workflow system.

All right. So uh I have an understanding now of what's going on with this particular endpoint. Now, I need to make sure that I can functionally test my entire API efficiently and quickly. So the way I'm going to do that is I'm actually gonna run the collection.

So I'm gonna move my mouse, move my mouse up to the top and select run collection from the menu. And at this point, I can actually take my requests and move them around into any order that I like I can specify anywhere from 1 to 100 or even 1000 iterations.

And I can even drive this with a data file, a CSV or a JSON file with key value pairs the key being a variable name in my collection. And then of course, the value being the value and this run will iterate once per row in that data file.

Um we're gonna keep it simple though. I'm just gonna go ahead and run it and we're gonna see all of these requests and the results of all of these tests emerge as the run completes.

I can click on view summary. Yeah. And I can see actually a summarized view of this and it looks like we definitely have a problem with response time here.

Um so what do I do about sharing these results with my developer again? Uh it turns out because we're all working in the same place. I don't necessarily have to do anything. My developer can come in, click on the collection, click on runs and they see the history of all the runs that have ever happened to this collection.

But if I want to draw their attention to it specifically, I can move over to the right, click on share, copy that link. And then for example, include that link in a comment on the collection again, just to draw attention to someone and say, hey, we need to take a look at this, this is an issue.

So again, create a comment, uh maybe call somebody out or just leave it for the community. Um and then insert this link. So again, cannot emphasize enough how important it is to bring everybody together in a governed way to collaborate inside the same workspace on the same stuff.

So my developer comes in, clicks on a request, can see the response, the request, the headers, everything that happened in that request, click on the link to the endpoint and go right again to the offending test.

So compare this now to emailing stuff back and forth to your QA team, obviously a huge improvement.

Um but let's talk about some other folks that might want to be involved in this process. Let's say I'm less technical. Uh I'm a program manager, even a customer and I'm not super comfortable looking at JSON that really doesn't help me to understand what this API is all about.

So what I can do is I can tell my developer or ask my developer rather to include a Postman visualization and visualization is super simple. It's just a Mustache template. It's got a very simple variable substitution mechanism will take values out of the body and substitute them into this template.

And now when I run this collection, we'll see the visualization again. If you're a developer, this is great. This is what you live for. This is what you want. If you're an API consumer, maybe not so much.

So I'm gonna add my visualization. Um again, it's just a simple Mustache template. And then when I run this collection, run the collection, run the collection. There we go. The little green ball will show up next to the visualized button. And that's gonna tell me I have a visualization.

Now, this is much more effective, right? If you're not a JSON person or an API person, it's much easier to understand the intention of this API by looking at this visualization right here. And this can be really cool. You can have geo visualizations, data, graphing, anything you want dynamic animations, it's up to you.

Um so again, in sort of conclusion at this point, what we've done is bring QA and dev and product management and API consumers together in the same place able to access all of these formerly hidden little hordes of treasure.

So the last thing we're gonna do is we're gonna make your APIs and AWS API Gateway more discoverable. And the way I'm gonna do that is I'm gonna click on the import button and I'm going to import an API directly from AWS.

So I've got this API over an API Gateway. I'm entering in my parameters, my ARM where this API lives. Yeah, probably should have added to this. Uh and once I do that, I'm gonna click import and what we're gonna get out of this is what's called an OAS definition.

Uh you might know it as a Swagger file. This is an open-source standard that defines everything about the contract in an API however, just looking at that, even as a developer, you're kind of like, not entirely sure, I know what to do with this. They are important and they will be more important in the future.

But right now what people want are friendly, easy to use Postman collections so that they can work with the API. By the way, these are the gateway to really cool features like runtime spectral linting. And if you know what that is, you know what that is.

All right, but I need a collection. So I'm gonna click on my accounts API and I'm gonna come over and just generate a collection from that definition. Boom. So we're like 30 seconds away from an API that was hidden in AWS API Gateway.

Now, we have an accessible collection full of requests that folks can run to interact with that API. Now, the last thing we're gonna do here is we're gonna make this API discoverable to everybody in your organization. And the way that we're gonna do that first is we're gonna publish it.

We're gonna create a named version 1.0 0.0. We can include release notes and I'm gonna publish this to the Postman private API network. And we'll talk about what that does in just a sec.

So, I'm gonna go ahead and publish it and now consider this question, you're a brand new developer. It's day one. Your boss says go work on the accounts API, what do you do? Right? Nobody really understands where APIs are, where they live in Postman.

You know that you go to the private API network, you go to the private API network. There we go. And there's all your APIs a curated collection of those canonical APIs that organization wants to be front and center for you to use.

I can browse forward or search for it. Click on the workspace, browse the documentation, understand what's going on and then I can finish up by clicking on view and workspace on the upper right hand corner and again, seconds from making my first call.

So think about what we just saw there. We had an API in the gateway that's doing its thing. It's delivering value for your customers, but nobody really knows about it. Nobody can discover it. It's incredibly hard to work with and interact with.

Two minutes later, we have a discoverable collection inside a Postman that anybody in the company can use to understand what that API does and possibly consume it.

Um so that's all I've got. Uh I just wanted to try to sort of broaden people's perceptions of Postman. It's not just a desktop testing tool. It can be a lot more.

So, thank you very much for your attention. I don't know that we have time for questions, but if you want to hit me and MC up or head by the booth later, we'd be really happy to talk to you guys. So, thank you very much.