Mastering API Fundamentals with POSTMAN and GraphQL

In today's fast-paced world of software development, Application Programming Interfaces (APIs) have become the backbone of communication between different software systems. APIs enable seamless integration and data exchange between applications, making them essential tools for developers. In this blog, we will explore API fundamentals and learn how to work with APIs using the powerful tool POSTMAN. So, let's embark on a journey to uncover the exciting world of APIs and POSTMAN.

What are APIs and their Importance in Modern Software Development?

APIs, or Application Programming Interfaces, are sets of rules and protocols that allow different software applications to communicate and interact with each other. They act as bridges, enabling data exchange, and functionality sharing between distinct systems. APIs have revolutionized modern software development in the following ways:

1. Seamless Integration: APIs make it easy for developers to integrate functionalities from one application into another, saving time and resources.
2. Scalability: APIs allow applications to scale easily by providing standardized interfaces that can handle increased traffic and user demands.
3. Improved User Experience: APIs enable the development of feature-rich applications that provide a smooth user experience, thanks to shared functionalities.
4. Collaboration: APIs foster collaboration among developers and organizations, encouraging the creation of ecosystems of interconnected applications.
5. Rapid Development: By utilizing APIs, developers can expedite the development process by leveraging pre-existing functionalities.

What is POSTMAN and Why Use It?

POSTMAN is a widely popular #API development and testing tool that simplifies the process of working with APIs. Whether you are a beginner or an experienced developer, POSTMAN offers a user-friendly interface to explore, test, and automate API interactions. Here are some reasons to use POSTMAN:

1. User-Friendly Interface: POSTMAN's intuitive UI makes it easy for developers to create, manage, and execute API requests.
2. API Documentation: POSTMAN enables you to generate clear and concise API documentation, making it easier for other developers to understand your APIs.
3. Collaboration: Teams can collaborate efficiently using POSTMAN, sharing API collections, and collaborating on projects.
4. Automated Testing: POSTMAN allows you to create automated test suites for APIs, ensuring that your applications perform as expected.

Working with APIs in POSTMAN

Making GET, POST, PATCH, and DELETE Requests:

• GET: Sending a GET request retrieves data from the server.
• POST: Sending a POST request creates new data on the server.
• PATCH: Sending a PATCH request updates specific data on the server.
• DELETE: Sending a DELETE request removes data from the server.

Query Parameters, Bodies, Headers, and Response Codes:

• Query Parameters: Used to filter and sort data in GET requests.
• Request Body: Used to send data in POST and PATCH requests.
• Headers: Used to provide additional information to the server, like authentication tokens.
• Response Codes: HTTP status codes that indicate the result of an API request.

Basic Scripting with POSTMAN

POSTMAN allows you to write scripts in JavaScript to automate tasks and add flexibility to your API requests. Basic scripting can help you handle dynamic data, environment variables, and response validation.

API Key Authorization

Many APIs require authorization to access certain endpoints. POSTMAN provides an easy way to add API keys to your requests to ensure secure and authenticated access.

Using Environment Variables in POSTMAN

Environment variables in POSTMAN help streamline workflows by allowing you to set values dynamically and use them across requests, making your API testing more efficient.

Automating Processes with Scripts in POSTMAN

POSTMAN allows you to create test scripts and workflows that can be automated, saving time and effort during the development and testing phase.

Generating API Call Code Snippets using POSTMAN's Codegen Feature

With POSTMAN's code generation feature, you can quickly generate code snippets in various programming languages for your applications. This feature accelerates the integration of APIs into your software projects.

Sending your first API request

Postman enables you to create and send API requests. Send a request to an endpoint, retrieve data from a data source, or test an API's functionality. You don't need to enter commands in a terminal or write any code. Create a new request and select?Send, and the API response appears right inside Postman.

API requests defined

APIs provide a structured way for one application to access the capabilities of another application. Typically, this communication happens over the internet by way of an API server. A client application (like a mobile app) sends a request to the server, and after the request processes the server returns a response to the client.

A request includes the URL of the API endpoint and an HTTP request method. The method indicates the action you want the API to perform. Here are some of the most common methods:

• GET?retrieves data from an API.
• POST?sends new data to an API.
• PATCH?and?PUT?update existing data.
• DELETE?removes existing data.

Sending an API request

When you're ready, open Postman and send your first API request.

• Select?+?in the workbench to open a new?tab.
• Enter?postman-echo.com/get?for the request URL.
• Select?Send.

Postman displays the response data sent from the server in the lower pane.

What happened?

In this example, Postman is acting as the client application and is communicating with an API server. Here's what happened when you selected?Send.

1. Postman sent a?GET?request to the?Postman Echo API?server located at?postman-echo.com.
2. The API server received the request, processed it, and returned a response to Postman.
3. Postman received the response and displayed it in the?Response?pane.

You used Postman to send an API request and got a response from the API server. It's okay to take a moment to sit back and reflect on how cool that is!

Next steps

Now that you've sent your first API request, you're ready to do more with Postman!

• You can send some more requests to the Postman Echo API, a handy tool you can use to test API requests in Postman. To learn more about using the Echo API, visit the?Postman Echo API documentation.
• When you're ready to learn more about building and sending requests in Postman, visit?Building requests.

Creating your first collection

Postman Collections?are a group of saved requests. Every request you send in Postman appears under the?History?tab of the sidebar. On a small scale, reusing requests through the history section is convenient. As your Postman usage grows, it can be time-consuming to find a particular request in your history. Instead of scrolling through your history section, you can save all your requests as a group for easier access.

To create a new collection, you can start by creating a new request first. You can create a new request from the sidebar in Postman.

To create a collection, do the following:

1. Select?New > HTTP

2. Enter a request in the request builder and select?Save.

3. Create a new collection by selecting?New Collection. Enter a collection name, and then select?Create.

4. Select?Save?to save the request in the new collection.

After you save the request, your new collection and the request are listed under?Collections?in the sidebar.

Creating a workspace

Postman workspaces enable you to organize and work together on API projects with your team. Within each workspace, you can share?APIs,?collections,?environments, and other Postman elements.

When you first open Postman, you will be in your default personal workspace. You can create more workspaces for your personal use and to work with teammates. To create more workspaces, you need to sign in to your?Postman account.

To create a new workspace, do the following:

1. Select?Workspaces?in the upper left. Select?Create Workspace?to add a new workspace. You can also search for existing workspaces using the search bar or select one from the dropdown list.

2. (Free, Basic, and Professional plans only) You can use?workspace templates?to help you set up a new workspace. Select a workspace template to populate the workspace with helpful information and sample collections, or select?Blank workspace?to create an empty workspace. Then select?Next.

You can also apply a workspace template to a newly created workspace. To learn more, see?Creating workspaces with a template.

3. Enter a?Name?and optional?Summary?for your workspace.

4. Choose the workspace's visibility:

• A?Personal?workspace is visible to you. If you're on an Enterprise team,?Super Admins?will also have access to any personal workspaces created within the team.
• A?Private?workspace is visible to you and to any team members, you invite to it (Professional and Enterprise plans only).
• A?Team?workspace is visible to everyone on your team.
• A?Public?workspace is visible to all Postman users.

5. Select?Create?or?Create Workspace.

Postman will switch to your new workspace when you create it. You can start editing and adding to it right away.

You can move between workspaces at any time by selecting from the dropdown?Workspaces?list in the upper left.

To learn more, see?Creating workspaces.

Capturing request data overview

Capturing HTTP traffic is an important tool for API development and testing. When you enable request capturing in Postman, you can inspect the requests passing between client applications and your API and save them to a collection. You can then use the saved request information to understand how your API is behaving and to assist with debugging.

Postman's built-in proxy and Postman Interceptor provide two ways to capture HTTP and HTTPS traffic. You can also use the proxy or Interceptor to capture and sync cookies to the Postman cookie jar.

To capture traffic, first start the proxy or Interceptor, and then begin a debug session. A session represents a specific time frame during which you want to capture traffic (for example, while a client application is sending a series of requests that you want to observe or debug).

After you begin a debug session, you can pause and resume capturing, or clear any captured traffic, without stopping the proxy or Interceptor. Use Postman's search and filtering capabilities to narrow down the requests based on the criteria you choose.

Contents

• Using the Postman proxy
• Using Postman Interceptor
• Capturing and syncing cookies

Using the Postman proxy

A proxy is an intermediary server that sits between a client application (like a mobile app or a web browser) and the destination server that the client is communicating with (like an API). When the Postman proxy is enabled and a client has been configured to use the proxy, a request from the client first goes to Postman, which then forwards the request to the destination server.

If you start a debug session while the proxy is enabled, Postman can capture any HTTP or HTTPS traffic passing through the proxy. You can then search or filter the requests, or save them to a collection.

Learn more about?capturing HTTP requests?and?capturing HTTPS traffic.

Using Postman Interceptor

Postman Interceptor provides another way to capture requests sent between a client and a server. Interceptor uses a Chrome plug-in rather than Postman's built-in proxy. With Postman Interceptor, you can capture HTTP and HTTPS requests sent from a Google Chrome browser.

Learn more about?using Postman Interceptor.

Capturing and syncing cookies

Along with capturing requests, Postman can capture cookies during a proxy or Interceptor debug session. You can manually add any captured cookies to the?Postman cookie jar?and use them when sending requests from Postman.

Postman's built-in proxy and Interceptor also support continuous cookie syncing. Once enabled, all captured cookies for the domains you specify are automatically synced to the Postman cookie jar.

Capturing HTTP requests

If you are using APIs to build client-side applications like mobile apps, websites, or desktop applications, you may want to inspect the actual HTTP and HTTPS request traffic that's being sent and received in the application. Sometimes you might discover APIs that aren't even documented. You can capture network traffic, including requests, responses, and cookies, using the proxy that's built into Postman.

You can also use the Postman proxy to automatically sync cookies from a Chrome browser to the Postman cookie jar. Learn more about?syncing cookies.

Contents

• How the built-in proxy works
• Using the Postman proxy
• Step 1: Enable the proxy
• Step 2: Start the proxy debug session
• Step 3: Configure the proxy on a client device
• Step 4: Run the proxy debug session
• Step 5: Stop the debug session and proxy
• Step 6: View the proxy debug session results

How the built-in proxy works

The Postman app has a built-in proxy that can capture HTTP and HTTPS traffic. Here's how it works:

1. The Postman app listens for any calls made by a client app or device using the proxy.
2. The Postman proxy captures the request and forwards it to the server.
3. The server returns a response to the Postman proxy, where it can also be saved.
4. The response is returned back to the client.

Similar to the?Interceptor Chrome extension, the Postman app proxy intercepts and captures your requests. Additionally, it can capture responses and cookies.

After you start the Postman proxy, you can start a proxy debug session, which is a time-bound session of traffic capture. You can start, pause, and stop a proxy debug session, then later start another one. Each debug session is logged in the?History?tab and displays the total session time, a traffic overview, and all traffic captured. You can also send requests and responses to a collection, and save cookies to the Postman cookie jar.

Using the Postman proxy

In the steps below, you will use the Postman app's proxy to inspect HTTP communication going to and from a phone. To get started, make sure your computer and phone are connected to the same local wireless network.

Step 1: Enable the proxy

You can't use the Postman proxy with the?Postman web app. Make sure you've installed the?Postman desktop app.

1. Select??Capture requests?in the Postman footer.
2. In the?Capture requests?window, select the?Via Proxy?tab.

3. In the upper right, select?Enable Proxy.

4. Enter a port number. By default, it's set to port?5555. Make a note of the port number you've used; you will use it later when configuring clients.

5. Select?Enable Proxy.

The proxy is running, but it won't capture traffic until you start a proxy debugging session.

Step 2: Start the proxy debug session

After the proxy is running, you can start a proxy debugging session. This is a time-bound session where captured traffic is saved in an entry in the?History?tab, and optionally into a collection. Once a proxy debug session is started, you can then pause, restart, or stop it. Before you start the session, you can select what traffic you want to go into it.

You can only have a single proxy or interceptor debug session running at the same time.

To start a proxy debug session, do the following:

1. Go to the?Via Proxy?tab of the?Capture requests?window.
2. Select?Save Responses for Requests?to save each request's responses. They will be saved along with the captured requests.

In responses with a?content-type?that has images, audio, or video, the content is intercepted but not captured. The only information captured is response headers, time taken, and the status code.

3. Select?Capture Cookies?if you want to capture cookies in addition to requests during the debug session.

You can also capture cookies and sync them to Postman without starting a debug session. Learn more about?syncing cookies.

4. Requests will be saved in a debug session in the?History?tab in the sidebar. Select?Save requests to a collection?and select a collection from the list to also save the requests there. To create a new collection in which to save requests, enter a name for the new collection and select the Create action.

5. If you save requests and responses to a collection, they're added chronologically by default. You can alternately group them in folders organized by domain name or endpoints. Under?Organize requests, select?the Domain name,?Endpoints, or both. Your requests and responses are then organized in folders in the selected collection.

6. Under?Configure Incoming Requests, there are more options you can use to limit the requests and responses captured:

• URL must contain?- Only capture URLs containing the specified string or regular expression.
• URL cannot contain?- Don't capture URLs containing the specified string or regular expression.
• Methods?- Only capture the selected methods.
• Resources?- Exclude requests with image, JS, or CSS responses.

7. Select?Start Capture.

The proxy debug session is started, but it won't capture anything until a device is configured with the proxy.

Step 3: Configure the proxy on a client device

1. Find the local IP address of the machine running the proxy:

• On macOS, you can find the computer's IP address in?System Preferences > Network. Select a network interface, and the IP address of your system will be shown on the right:

• On Windows, select?Start > Settings > Network & Internet> Wi-Fi?or?Ethernet. Your IP address is listed under?Properties.

2. Open the wireless settings of your client device and update the configuration of the network connection to use an HTTP Proxy. For example, in iOS:

• Select?Settings > Wi-Fi.
• Select next to a Wi-Fi connection.
• Select?HTTP Proxy > Configure Proxy > Manual.
• Set?Server?and?Port?to the local IP address and proxy port.
• Select?Save.

3. In the Postman app, open the?Proxy debug session?window. Open the device's web browser or application and HTTP traffic will start passing through the app or the browser.

Configuring a proxy on other devices

The broader development community has published some useful tutorials for setting up a proxy server on various operating systems:

• Windows
• Linux
• macOS
• Android

Step 4: Run the proxy debug session

While your capture session is running, the?Proxy Debug Session?window will show captured traffic as you use the browser or apps on the client device.

There are several controls you can use to limit, organize, and investigate traffic as it's captured:

• Select the name?Proxy to debug the session?and enter another name to change the window name.
• The?Configure incoming requests?controls at the top of the window enable you to limit captured traffic. Select items from?Methods,?Status Codes,?Resources, and?URL?to limit the traffic. These controls are similar to the ones you set initially in Step 2 above, but they limit what's being captured, instead of what's going through the proxy.
• Select or deselect?Save Responses for Requests?and?Capture Cookies?to choose whether to collect responses or cookies.
• Select the?Requests?tab to get information about incoming requests and responses, or?Cookies?to get information about captured cookies.
• Use the search box to find specific requests.
• Select?>?next to a request to expand it for more details.
• Select the URL in the?URL?column to open the request as a new API request in Postman.
• Below the request list, there are controls to change the collection where the traffic is being sent, and if it needs to be grouped by domain name or endpoints.

When you select one or more requests from the list on the?Requests?tab, you can use the following controls:

• ?Delete?- delete the request.

When you select one or more cookies from the list on the?Cookies?tab, you can use the following controls:

• + Add to Cookie Jar?- add the request to the Postman cookie jar.
• ?Delete?- delete the cookie.

The bottom right corner shows the total time of the capture session, along with the total size of captured traffic. If you want to temporarily stop the capture session, select?Pause. To restart the session, select?Resume.

Step 5: Stop the debug session and proxy

When you're done with your debug session, select?Stop?in the lower right corner. This will finish the debug session, and the results of the debug session will be saved in the?History?tab.

After stopping the session, the proxy is still running. Select??Capture requests?in the Postman footer, and you can either start another debug session or select?Disable proxy?to turn off the proxy.

Step 6: View the proxy debug session results

After completing a debug session, details from the session are located in the?History?tab, named?Proxy debug session.

When you open a saved debug session, the top header displays the session start time, total size, duration, and source.

The?Overview?displays summary graphs of the traffic captured in the session. You can select graphs summarizing traffic by method, domain, data mode, or return status code.

The?Requests?and?Cookies?tabs display requests, responses, and cookies, similar to the same tabs available during a capture session. The same options for searching, expanding, saving, and deleting items described in Step 4 are available. You can also add selected requests to a collection. Use the controls at the bottom of the table to limit the number of items per page and view the pages of results.

You can rename a proxy debug session by selecting the name at the top of the window and entering a new name. Select the more actions icon?next to the debug session name to rename or delete the session.

GraphQL overview

Postman can make HTTP calls using GraphQL, an open-source data query and manipulation language for APIs.

You can use GraphQL with Postman in two ways:

• Using the Postman GraphQL client
• Postman's GraphQL client enables you to easily explore schemas with introspection and quickly build?queries, mutations, and subscriptions?to get the data you need. See?About the GraphQL client?to learn more.
• Using the Postman HTTP request interface
• Postman's HTTP request interface supports sending GraphQL queries in the request body, using GraphQL variables, and introspection, and importing GraphQL schemas. See?Using GraphQL requests with the HTTP request interface?to learn more.

Making your first request with the GraphQL client

Get started with GraphQL by creating a query and executing it using Postman’s echo endpoint.

Contents

• About GraphQL requests
• Making a GraphQL query with Postman
• Next steps

About GraphQL Requests

Every GraphQL request requires a URL and a query. The URL is the endpoint where the data is hosted, and the query defines what exactly needs to be retrieved from this data source. A GraphQL request can also have a schema configured to inform you of the data fields available from the server that can be included in the query. The request can also contain additional information such as authentication, headers, and settings based on the requirements specified by the API.

Using a GraphQL request, you can execute three different types of Queries:

• Queries?- Queries retrieve data from the server by specifying data fields and passing required arguments.
• Mutation?- Mutation-type queries allow you to manipulate the data available on the server. You can create, update, and delete data records by selecting the fields and passing the values as arguments.
• Subscription?- For a live data source with frequently-changing data, you can subscribe to the data available in different fields. This enables the server to send the data requested over a persistent connection.

Making a GraphQL query with Postman

This example creates and executes a GraphQL query using the interactive query builder.

If you are using the Postman web app, you must use the Postman Desktop Agent. See?About the Postman Agent?for more information.

1. In Postman, select?New > GraphQL?to open a request in a new tab. (In the Postman desktop app, you can also select??+N?or?Ctrl+N, then select?GraphQL.)
2. In the URL bar, enter?https://graphql.postman-echo.com/graphql. This will load the schema using introspection.
3. In the query explorer on the left, select the?hello?field and select?person,?age, and?name?as arguments.
4. Enter your age and name in the input boxes next to?your age?and?name. You should also see a fully-formed query based on your selections on the right.
5. Select?Query.

Integrating with Postman

You can connect Postman to your API workflows with integrations for popular third-party solutions. Use integrations to automatically share data between Postman and the other tools you rely on for API development. Sync your collections and API definitions to a source control repository. Send monitor alerts to your monitoring service or team messaging app. Or view your continuous integration (CI) builds from within Postman.

The maximum number of integrations you can use is determined by your Postman plan.?Learn more about what's included with each plan.

Contents

• Adding integrations
• Viewing or editing integrations
• Installed apps
• Static IP support
• CI integrations

Adding integrations

To view available integrations, select?Integrations?on the Postman?Home?page, then select?Browse All Integrations. On the?Browse Integrations?page, search and select the tool or service you want to integrate with.

Each integration page explains how to use the integration and what it can do. Depending on the tool or service you're integrating with, more than one integration may be available. Select?Add Integration?next to the integration you want to add. Enter your account authorization details and any other required information to complete the setup process.

Viewing or editing integrations

You can view the integrations that have been configured for your team from the?Browse Integrations?page. Search and select the tool or service you want to view integrations for. Select?View?or?View All?next to an integration to view any integrations that have already been configured.

You can also view integrations that have been configured for a collection or monitor. Open the collection or monitor, and then select the information icon??in the right sidebar to view any configured integrations.

Select a configured integration to view more details. From here you can take the following actions:

• Refresh Run Log?- View the most recent integration runs.
• Edit Integration?- Change any configuration settings for the integration, then select?Save Changes. Not all settings can be changed, depending on the integration. If needed, delete the integration and add a new integration with the settings you want.
• Delete Integration?- Delete the integration. You can add the integration again later if needed.

Installed apps

Adding an integration requires you to authenticate with the third-party app or service you are connecting to Postman. For supported integrations, you can store the authorization details in an?installed app. Anyone on your team can then use the installed app to add a new integration, instead of authenticating with their own credentials.

Learn more about?adding and using installed apps in integrations.

Static IP support

You must allowlist a static IP address to enable integrations and custom webhooks that access hosted (private) networks. Static IP support is available for the following integrations:

• GitHub custom domain backup
• GitLab custom domain backup
• Custom webhooks

Contact your IT team to allowlist the following static IP in your firewall:

• US East:?3.212.102.200

Once you allowlist this IP address, collection backup integrations and custom webhooks will be able to connect to your private network.

DNS records use the public IP address for instances that are behind a firewall or that can't be accessed on the internet.

CI integrations

Continuous integration and continuous delivery (CI/CD) is a core part of the?API development workflow. Postman integrates with popular CI tools so you can view details about API builds in the same place where you define and test your API.

After you set up CI integration, you can view the status of builds or start a new build, all from within Postman. You can also run?API tests?created in Postman as part of your CI pipeline using the?Postman CLI?and the Postman API.

Configuring CI integration

To set up CI integration for your API, first set up your CI project and then connect Postman to your CI tool. After you set up CI integration, information for CI build jobs is available in Postman. Select?Test and Automation?for your API to view recent build jobs, see the build status, and even start a new build.

To connect your API to your CI project, see the steps for your CI tool:

• Azure Pipelines
• Bitbucket Pipelines
• CircleCI
• GitHub Actions
• GitLab CI/CD
• Jenkins
• Travis CI

Configuring the Postman CLI for CI

Running API tests as part of your CI pipeline helps to keep expectations between your API producers and consumers in sync. The Postman CLI can also perform?Postman API Governance and API Security checks?as part of your CI pipeline (Enterprise teams only).

To run your API tests along with each build and, optionally, your API Governance and API Security checks, first generate the Postman CLI configuration code in Postman. Then add the configuration code to your CI project. Each time a CI build runs, the Postman CLI uses the Postman API to run the collections that contain your tests. You can view the results of your tests in Postman.

To configure the Postman CLI to run API tests, see the steps for your CI tool:

• Azure Pipelines
• Bitbucket Pipelines
• CircleCI
• GitHub Actions
• GitLab CI/CD
• Jenkins
• Travis CI

Conclusion:

In conclusion, APIs are vital components of modern software development, enabling seamless integration, scalability, and improved user experiences. POSTMAN, with its user-friendly interface, automation capabilities, and extensive documentation features, becomes an indispensable tool for working with APIs. From making simple requests to generating code snippets, POSTMAN streamlines the entire API development and testing process. As you continue your journey as a Postman Student Expert, embrace the power of APIs and POSTMAN to create cutting-edge applications and explore the endless possibilities they offer in the world of software development. Happy API building!