Forem: Sean Keegan

First 5 Things to Try If You’re New to Postman

Sean Keegan — Wed, 22 Jun 2022 09:29:27 +0000

Here at Postman, we’ve got a mission to democratize APIs and allow everyone to use and build APIs with the Postman API Platform — as we move toward an API-first world. We recently crossed the 20 million user threshold, and we’re not stopping there. Whether you’re brand-new to Postman or just looking for interesting new ways to get started, we’ve got you covered.

Before trying any of the specific features below, you’ll need to create a Postman account, and then sign in. Postman can be used directly from your favorite browser or you can download the desktop application.

Once you’re logged in, dive in and explore these five cool things you can do to get started with Postman.

1. Send a request

Postman began as a simple API client—a tool to make it easy to send requests and inspect responses, so there’s no better place to start than here. We’ve removed the need to write any code or enter any commands in a terminal. Pick your favorite API, type the request URL into the text box, and then click the blue Send button. If you don’t have an API to explore yet, feel free to hit the Postman Echo API by sending your request to postman-echo.com/get.

After you send your request, you’ll see the response data sent from the server in the lower pane. From here, you can test out other HTTP verbs such as POST, PUT, DELETE, etc.

While most people may know Postman as an HTTP client, the functionality hardly stops there. Postman also supports requests using WebSockets, GraphQL, and gRPC.

2. Add a test

Testing an API can have different meanings to different users. To some, it may mean sending a request and inspecting the response as we did in the first step. To others, it could mean writing assertions to validate that an endpoint is returning the appropriate responses.

In general, tests confirm that your API is working as expected. The easiest way to get started with writing tests in Postman is to use the snippets on the right side of the Tests tab. Clicking on a snippet will append the JavaScript code into the editor. You can update the boilerplate code or write your own tests from scratch if you’re comfortable.

Send your request again, and now you can see the results of your test on the bottom, under the corresponding Tests tab in the response viewer:

For information on more advanced testing workflows, check out this blog post.

3. Create and run a collection

Postman Collections are the heart and soul of lots of advanced Postman features. Collections are how you group your Postman requests and examples to keep your workspace organized.

Save your example request to a collection and add a few more if you like. Once you have your requests saved in a collection, try running them using the Collection Runner. Click on the three dots next to your collection name, select Run collection from the dropdown menu, and then click the blue Run button to open the Collection Runner in a new window.

When you run your collection in Postman using the Collection Runner, you will see requests being sent and the tests running:

4. Create a workflow using Postman Flows

Postman Flows is a low-code API workflow builder currently in open beta. It lets you connect APIs logically without having to write advanced code. You can find existing Flows and create new ones by navigating to the Flows tab in the left sidebar.

To get started, you’ll want to understand the basic building blocks and how they work in this Postman Flows tutorial. But play around and use Flows to chain requests, handle data, and create real-world workflows right in your Postman workspace. For hands-on examples that you can fork and customize, check out this public workspace.

Chaining requests in Postman Flows

5. Share your work

Postman is the leading API collaboration platform for a reason: we make it easy to share your work. Whether you’re working with a single friend on a small project or you’re part of an enterprise company with hundreds of developers actively working on a public API, you control what is visible and to whom.

If you’ve built something the world needs to see, publish it to the API network! This will allow all Postman users around the world to search for and fork your collection. Don’t forget to explore it on your own to see what’s out there.

You can also invite people to your team and collaborate in real time together. You’ll be able to work in the same environment and avoid context switching as you develop your APIs. While you’re at it, show off your team to the rest of the world by making a team public profile.

Keep exploring—to the next level

Now that you’ve got some of the basics down, check out our 10 Postman Features Everyone Should Know public workspace. Did you know Postman has its own API? Or that you can visualize responses directly in Postman? Discover that and many other useful tools.

And if you’re looking for options to take your exploration in Postman to the next level, check these out:

Build request workflows
Test automation with Newman or Postman monitors
Leverage third-party integrations
Explore how to document your API
Use mock servers throughout the API lifecycle

More helpful resources

Here are a few more handy resources if you get stuck or just want to learn more:

Postman documentation for detailed explanations and additional resources
More of a visual learner? The Postman Youtube channel is chock full of educational content
Earn an official Postman badge and prove your Postman knowledge
Lean on the community and other Postmanauts by joining the Postman community forum or browsing other community content

Technical review by Arlemi Turpault.

The post First 5 Things to Try If You’re New to Postman appeared first on Postman Blog.

Adding External Libraries in Postman

Sean Keegan — Wed, 27 Apr 2022 16:00:06 +0000

The Postman sandbox is an environment provided to execute Javascript code in the pre-request and tests scripts for a request. The sandbox has built-in JavaScript APIs via the pm and postman objects for testing your request and response data. While these objects help a ton with testing your API and workflow control, you may need additional functionality.

This is where external libraries come in. There are several helpful libraries built into the sandbox whose methods and functionality are available with very little extra work needed. However, you also have the ability to leverage additional external libraries. We’ll first look at how to use the libraries that are available out of the box, then review some methods for adding your own desired libraries.

Get started right away

If you’re a hands-on learner and want to see working examples, fork the Adding External Libraries collection to see the various methods of adding external libraries.

Using built-in library modules

Some popular JavaScript and NodeJS modules (such as moment, lodash, and querystring) are included in the Postman sandbox and can be imported by calling the require method. To do this, use the require method by passing the module name as a parameter and assigning the return object from the method to a variable.

Here’s a basic example of using the format method from the moment library to format a date:

let moment = require('moment');
let jsonResponse = pm.response.json();
console.log("formatted date =", moment(jsonResponse.args.randomDate).format("MMM Do YYYY"));

To see the full list of available libraries with links to the documentation for each, check out the Postman Learning Center.

Use built-in libraries, like lodash, by importing them with the require statement

Importing additional external libraries

For libraries that are not included in the Postman sandbox, you may still be able to make use of their functionality within Postman. If a CDN version of a library exists, or you have the pure JavaScript code for that library, we’ll look at two methods of importing a library. For these examples, we’ll import Day.js, a JavaScript library to help parse and format dates, and see how to use some of the Day.js methods.

Pull a library from a CDN

If a CDN version of a library exists, one option is to make a request to the CDN page hosting the library in the pre-request or tests tabs. Follow these steps:

Once you receive a response, convert the response to a string and save it as a collection variable.
With the code saved as a string, use the eval function to evaluate the JavaScript code.
After running the eval function, the methods for the desired library are attached to the this keyword and can be used in the sandbox.

pm.sendRequest("https://cdnjs.cloudflare.com/ajax/libs/dayjs/1.11.0/dayjs.min.js", (err, res) => {
   //convert the response to text and save it as an environment variable
   pm.collectionVariables.set("dayjs_library", res.text());

   // eval will evaluate the JavaScript code and initialize the min.js
   eval(pm.collectionVariables.get("dayjs_library"));

   // you can call methods in the cdn file using this keyword
   let today = new Date();
   console.log("today=", today);
   console.log(this.dayjs(today).format())
})

Security note: Make sure you feel comfortable with the library you’re importing this way. The eval function is a powerful and helpful tool, but since it just evaluates JavaScript code represented as a string, it can be a security risk to run random code with the eval function.

Importing the Day.js library by sending a request to the CDN and saving it as a collection variable

Load a library from a variable

If you’d rather not make an additional API request every time you make your initial request, you can avoid it by loading in the library code ahead of time. Follow these steps:

Copy and paste the code of the library into a collection variable. Once saved, you can access the code in the Postman sandbox by creating and setting a variable equal to the collection variable.
Next, run an IIFE (Immediately Invoked Function Expression) which will give you access to the dayjs methods in the sandbox.
You’ll now have access to the dayjs methods directly and can call them without using the this keyword.

const dayjs_code = pm.collectionVariables.get('dayjs_code');

// Invoke an anonymous function to get access to the dayjs library methods
(new Function(dayjs_code))();

let today = new Date();
console.log(dayjs(today).format())

Here is an example of pasting the minified code as a collection variable to access it in the Tests tab. It may look scary, but it’s just condensed to limit the number of characters:

Try it out yourself

If you’re a hands-on learner, don’t forget to check out and fork the Adding External Libraries collection in our Postman Answer public workspace. You’ll see code samples for all three methods of importing libraries discussed in this post and be able to play around with adding new libraries of your choosing. Happy testing!

Technical review by Arlemi Turpault

The post Adding External Libraries in Postman appeared first on Postman Blog.

Using Mock Servers throughout the API Lifecycle

Sean Keegan — Mon, 28 Feb 2022 17:52:26 +0000

Throughout every stage of the development process, there are unexpected bumps and setbacks. These often delay or completely halt progress. As we integrate with more and more APIs, we inevitably spend more time than we‘d like debugging (individuals spend 16% of their time debugging APIs, compared to 10% in their ideal state). Whether you rely on external pieces of technology or just have multiple teams attempting to work concurrently, there are plenty of ways to get jammed up.

Whatever the case may be, it’s infuriating when you’re working with an API, internal or external, and development is interrupted. Fret no more—mock servers have you covered for all stages of the development lifecycle.

What exactly is a mock server?

Let’s back up a second to answer the above question. What exactly is a mock server? In the Postman API Platform, a mock server is a tool that allows you to make API requests and simulate the corresponding responses. When you send a request to a mock server, Postman will match the request configuration to the examples that were saved for the request and respond with the data that was added as an example.

This allows you to see what an API would potentially deliver in a production instance by mocking the request and example responses. Mock servers enable rapid development of API infrastructure without having to write code. This shortens the feedback loop and allows developers to iterate more quickly.

Postman makes it easy to create a mock server in several ways. In this blog post, we’ll cover some of the reasons why you may want to use mock servers, and then show you how you can add them to your workflow.

Using mock servers for collaboration

Development typically doesn’t happen by a single person or even a single team. Even small-scale projects can have frontend developers, backend developers, QA engineers, etc. To work as quickly as possible, different teams often work on different parts of the project at the same time.

Mock servers help keep this process as efficient as possible. They are versatile in that they can be used in many different stages of the API development lifecycle—for both API producers and consumers. Let’s consider an example where the frontend team wants to start integrating with data coming back from the backend/server. If the API endpoints are not fully configured and working, frontend engineering may not be accurate or even possible.

This is a basic example of where mock servers can be used in the earliest design part of the process. Instead of waiting for the endpoints to be built and deployed, you can use Postman to spin up a mock server from an API specification that will simulate server responses to be used on the frontend. The UI developer can get started right away by querying the mock server and working against the expected responses. When the actual API is production-ready, swap out the URL that accesses the mock API responses with the URL for the real API (you may also need to add any necessary authorization at this point.) The video below walks through how to set up and call a mock server:

Test efficiently by mocking external dependencies

APIs and projects don’t live in a vacuum. Backend development constantly integrates with other services. Unfortunately, calls to external servers are completely out of your control. They can produce unreliable, unexpected results. Servers go down and return 503 Service Unavailable errors for example. As referenced earlier, 16% of overall time working with APIs is spent debugging. If your project relies on a suite of external APIs, there’s a chance that at some point you’ll try to access an API that is experiencing failure and you’ll need to figure out how to continue. These instances don’t need to be a total blocker.

It’s common to have a call to an external server or API as a crucial component of your workflow. To avoid relying on external services during development, this is another scenario where we can use mock servers. Mock servers simulate the experience of hitting an external server and returning an expected response.

In this scenario, mock servers aid in the local testing and development phase of the development lifecycle. Let’s explore a theoretical example:

Say you have an e-commerce application with an ordering flow (pictured below). Your API is coupled with a shipping service that needs to stay in sync. Whatever is added to the cart in the e-commerce app needs to similarly be added to the cart for the shipping service. This allows the shipping service to keep track of what needs to be shipped. Essentially, every time a request is made to your own API, there will be a request to the shipping service API as well.

A visual example of testing an e-commerce site but productivity is stopped because of an issue in the Shipping API

If you’re testing out your integration, you can use Postman to test each API directly. By isolating individual APIs in your workflow, you can determine if there are any issues with specific APIs. If the shipping API returns a 503 Service Unavailable error, this could halt further development or testing. By configuring a mock server for the external shipping API, you would still be able to continue working based on expected results from the shipping API despite it being down. This is a repeatable process for all your dependencies that are APIs.

Below is the same workflow but the Shipping API has been swapped out for a mock server simulating the Shipping API requests and responses. Now, as long as the internal APIs are working as expected—even if the Shipping API fails—testing is not affected by the failing API.

A visual example of testing the e-commerce site while using a mock server to simulate the Shipping API

Talk data to me

Data is one of the most important pieces of the API ecosystem. Regardless of the HTTP verb or protocol used, sharing data between applications and systems is at the heart of all things APIs.

Data can contain sensitive personal user information, so you may not want to test with real-user data. But it can get boring and not realistic if all your placeholder data is “John Doe” who lives at “123 Main Street.” Whether you’re interested in protecting private data or simulating an actual production-like workflow, mocks help manage both everyday testing and tricky use cases alike.

Creating dynamic data for your mock servers within Postman is a valuable option. Postman comes equipped with several external libraries available, including Faker.js—a dummy data generator capable of producing fake addresses, names, phone numbers, etc. Mock servers can be generated from a series of tightly coupled requests and the corresponding response examples. Instead of using the default saved example, you can customize the response to fit your needs. Below is a screenshot of a saved example from the request that gets all books from a library:

In this case, this is obviously not sensitive data. But if the author and id fields were something like name and credit card number, this could be information you’d rather simulate in a sensitive environment. Or if the developers just want to work with non-static data to simulate a real workflow, dynamic variables can be used.

By editing the response example to contain dynamic variables, we can enable our mock server to take advantage of the built-in Faker.js library and provide dummy data. In the video below, we show you an example of returning random colors from a mock server endpoint:

The internet is an unpredictable place—let mocks bring order to your development lifecycle

In sports, a common refrain is to “control the controllables.” This generally means focusing your energies on the things you can do to shape the outcome of an even—like your attitude and effort.

With the aid of mock servers, a similar mindset can be adopted for development. While we can’t control the stability of an external API, we can use a mock server to simulate what should happen, reducing confusing or unexpected hiccups along the way. Let mock servers be the stability you need to do the work you want.

For some hands-on practice and exploration of mocks, check out this Mock Services collection for day 10 of the 30 Days of Postman coding challenge for developers.

Technical review by Arlemi Turpault.

The post Using Mock Servers throughout the API Lifecycle appeared first on Postman Blog.

The Twitter API: Confessions of a User

Sean Keegan — Fri, 30 Apr 2021 20:10:40 +0000

I recently wrote a blog post about my experience creating a Twitter hashtag search bot. While the accompanying Postman Collection works as I described, I eventually realized I made some incorrect assumptions and inefficient decisions. After chatting with Twitter Senior Developer Advocate Andy Piper during the “Searching for the Hidden Gems in the Twitter API” Postman livestream, I’m here to muse on some of my learnings and come clean about my previous complaints regarding the Twitter API.

To read, or to code?

I think all developers can identify with the dilemma of where to start: reading the docs first or diving in headfirst with an example. When working with a new API, I often try to take a sample request and get it working in my own Postman environment. From there, it’s a series of self-guided trials and errors, and I occasionally go back to reference the docs.

In the case of building a Twitter hashtag search bot, I chose to jump right into the Twitter API v2 collection in Postman. It was pretty easy to enter my auth credentials and start sending requests. But this same convenience ended up being a bit of a double-edged sword, as I arguably jumped in too swiftly. My hasty queries led to some misunderstandings and frustrations that could have potentially been avoided had I read through the documentation more thoroughly. Going forward, I may invest a bit more time upfront to understand the full functionality of an API.

Twitter taking after GraphQL?

I wrongly accused the Twitter API of lacking certain functionality. When I searched for tweets with a certain hashtag, I easily returned the content of the tweets, but I couldn’t seem to get any info on the person who sent the tweet without making a second request. Looking at the request below, you can see the query params include user.fields with values of created_at,id,name,username. Based on these request parameters, I expected the response for each tweet that was returned to include user info. But if you look at the response object, those values are nowhere to be found.

Example request with several values in the user.fields param, yet the corresponding response includes no user info

This led to my incorrect assumption that Twitter was intentionally withholding certain information from the response based on my API access level. But this seemingly frustrating snag is actually an intentional API design choice. Andy taught me that the Twitter API has tons of data for every tweet, and the API response used to return everything. However, with so much info available, responses can get very large and unwieldy if all the available data is sent in the response.

The Twitter API now lets you have more control over what gets returned in your response. This is similar to GraphQL in that you can request specifically what you want to get back. As they describe in their official tweet object documentation, “Tweets are the basic building block of all things Twitter.” From the tweet object itself, there are several child objects from which you can request more data. One of these child objects is the user object, which returns information about the users of tweets.

How to include the child object

If you’re using the Twitter API from within Postman, you need to include a query parameter called expansions. Expansions allow you to expand objects referenced in the payload, such as the user object mentioned above. Below is the updated request with the new expansions key activated and author_id as the value:

And here’s the new response:

You’ll notice it has a new object tacked on at the bottom, called includes with an array called users. Success!

Also, notice that the value for author_id in the data object matches with the value for id in the users object. Using these matching IDs, you can sync the user information for each tweet. With a little bit of JavaScript code (see below), you can loop through both objects and pair them up:

Want to contribute?

Are you a developer whose stomach gets queasy at the thought of nested for loops like the code above? Or just have some cool ideas to make this bot even better? If so, please feel free to help improve my code for the Twitter hashtag search bot. Postman’s public workspaces make it easy to fork a collection, make some improvements, and submit a pull request. Click here to go to the collection and then click “Fork” in the central menu bar to bring the collection into your own workspace.