From 607f1c92bfd256123a948bc7c225709a35db9377 Mon Sep 17 00:00:00 2001 From: Jonathan Konrath <80709817+jkonrath-postman@users.noreply.github.com> Date: Thu, 19 Oct 2023 10:14:28 +0530 Subject: [PATCH 1/2] Remove pages, change links --- src/components/LeftNav/LeftNavItems.jsx | 51 +--- src/pages/labs-overview.md | 12 +- .../graphql-client/first-graphql-request.md | 49 ---- .../graphql-client/graphql-client-overview.md | 27 -- .../graphql-request-interface.md | 104 -------- .../mqtt-client/first-mqtt-request.md | 80 ------ .../mqtt-client/mqtt-client-overview.md | 27 -- .../mqtt-client/mqtt-request-interface.md | 77 ------ .../websocket-client-overview.md | 237 ------------------ 9 files changed, 16 insertions(+), 648 deletions(-) delete mode 100644 src/pages/postman-api-client/graphql-client/first-graphql-request.md delete mode 100644 src/pages/postman-api-client/graphql-client/graphql-client-overview.md delete mode 100644 src/pages/postman-api-client/graphql-client/graphql-request-interface.md delete mode 100644 src/pages/postman-api-client/mqtt-client/first-mqtt-request.md delete mode 100644 src/pages/postman-api-client/mqtt-client/mqtt-client-overview.md delete mode 100644 src/pages/postman-api-client/mqtt-client/mqtt-request-interface.md delete mode 100644 src/pages/postman-api-client/websocket-client/websocket-client-overview.md diff --git a/src/components/LeftNav/LeftNavItems.jsx b/src/components/LeftNav/LeftNavItems.jsx index 1636e6dc4..5bee5c721 100644 --- a/src/components/LeftNav/LeftNavItems.jsx +++ b/src/components/LeftNav/LeftNavItems.jsx @@ -45,61 +45,30 @@ export const leftNavItems = [ { name: "GraphQL Client", parentSlug: "graphql-client", - url: "/postman-api-client/graphql-client/graphql-client-overview/", - caret: true, - subMenuItems1: [ - { - name: "GraphQL overview", - url: "/postman-api-client/graphql-client/graphql-client-overview/" - }, - { - name: "Using GraphQL request interface", - url: "/postman-api-client/graphql-client/graphql-request-interface/" - }, - { - name: "Making your first GraphQL query", - url: "/postman-api-client/graphql-client/first-graphql-request/" - }, - ], + url: "https://learning.postman.com/docs/sending-requests/graphql/graphql-overview/", + caret: false, + subMenuItems1: [] }, { name: "gRPC Client", parentSlug: "grpc-client", url: "https://learning.postman.com/docs/sending-requests/grpc/grpc-client-overview/", subMenuItems1: [], - caret: false, + caret: false }, { name: 'WebSocket Client', parentSlug: 'websocket-client', - url: '/postman-api-client/websocket-client/websocket-client-overview/', - caret: true, - subMenuItems1: [ - { - name: 'Using WebSocket requests', - url: '/postman-api-client/websocket-client/websocket-client-overview/', - }, - ], + url: 'https://learning.postman.com/docs/sending-requests/websocket/websocket/', + caret: false, + subMenuItems1: [] }, { name: "MQTT Client", parentSlug: "mqtt-client", - url: "/postman-api-client/mqtt-client/mqtt-client-overview/", - caret: true, - subMenuItems1: [ - { - name: "MQTT overview", - url: "/postman-api-client/mqtt-client/mqtt-client-overview/" - }, - { - name: "Using MQTT request interface", - url: "/postman-api-client/mqtt-client/mqtt-request-interface/" - }, - { - name: "Creating your first MQTT request", - url: "/postman-api-client/mqtt-client/first-mqtt-request/" - }, - ], + url: "https://learning.postman.com/labs/postman-api-client/mqtt-client/mqtt-client-overview/", + caret: false, + subMenuItems1: [], } ]; diff --git a/src/pages/labs-overview.md b/src/pages/labs-overview.md index 26b027f82..050d990d0 100644 --- a/src/pages/labs-overview.md +++ b/src/pages/labs-overview.md @@ -3,7 +3,7 @@ title: "Welcome to Labs!" order: 1 page_id: "introduction-to-labs" warning: false -updated: 2022-07-07 +updated: 2023-10-19 contextual_links: - type: section name: "Prerequisites" @@ -30,7 +30,7 @@ contextual_links: name: "WebSockets" - type: link name: "Using WebSocket Requests" - url: "/postman-api-client/websocket-client/websocket-client-overview/" + url: "https://learning.postman.com/docs/sending-requests/websocket/websocket/" - type: link name: "Github Issues" url: "https://github.com/postmanlabs/postman-app-support/issues" @@ -46,13 +46,13 @@ Flows is a visual tool to create API workflows. You can use Flows to chain reque ## API Client -The API Client team has diligently been working on supporting more protocols within Postman. We started out by addressing WebSockets (and Socket.IO) and continued on with gRPC. We will continue to support and evolve each of these protocols. GraphQL is our next target. If there are other protocols that you think we should address, please check out the [GitHub Issues](https://github.com/postmanlabs/postman-app-support/issues) discussions. +The API Client team has diligently been working on supporting more protocols within Postman. We started out by addressing WebSockets (and Socket.IO) and continued on with gRPC. We will continue to support and evolve each of these protocols. If there are other protocols that you think we should address, please check out the [GitHub Issues](https://github.com/postmanlabs/postman-app-support/issues) discussions. ### GraphQL -APIs made with GraphQL allow clients to ask the server for exactly the data they need. This is enabled by a powerful query interface and a runtime to execute those queries making it easier for developers to quickly explore and experiment with the client’s functionalities. Contrary to REST, which makes your chunks of data available on multiple endpoints, GraphQL makes working with data simpler and faster with a single endpoint. Plus, GraphQL is schema driven, which means more transparency in terms of API functionality and lower dependency between teams building the client and the server. So, a client can introspect the schema from the server to get an idea about the available data fields, send queries specifying fields to retrieve or manipulate the stored data. The server does exactly what was asked from it and returns only the data requested in the query. Combining these features, GraphQL provides users with a flexible, fast and predictable API experience, making it one of the most popular API technology. +APIs made with GraphQL allow clients to ask the server for exactly the data they need. This is enabled by a powerful query interface and a runtime to execute those queries making it easier for developers to quickly explore and experiment with the client’s functionalities. Contrary to REST, which makes your chunks of data available on multiple endpoints, GraphQL makes working with data simpler and faster with a single endpoint. Plus, GraphQL is schema driven, which means more transparency in terms of API functionality and lower dependency between teams building the client and the server. A client can introspect the schema from the server to get an idea about the available data fields, send queries specifying fields to retrieve or manipulate the stored data. The server does exactly what was asked from it and returns only the data requested in the query. Combining these features, GraphQL provides users with a flexible, fast, and predictable API experience, making it one of the most popular API technology. -[Read more here...](/postman-api-client/graphql-client/graphql-client-overview) +[Read more here...](https://learning.postman.com/docs/sending-requests/graphql/graphql-overview/) ### gRPC @@ -64,4 +64,4 @@ gRPC is a schema-driven Remote Procedure Call (RPC) framework often used to enab The WebSocket protocol provides a way to exchange data between a client and server over a persistent connection. The data can be passed in both directions with low latency and overhead, and without breaking the connection. WebSockets provide a bidirectional, full-duplex communications channel that operates over HTTP through a single TCP socket connection. This means the server can independently send data to the client without the client having to request it, and vice versa. -[Read more here...](/postman-api-client/websocket-client/websocket-client-overview/) +[Read more here...](https://learning.postman.com/docs/sending-requests/websocket/websocket/) diff --git a/src/pages/postman-api-client/graphql-client/first-graphql-request.md b/src/pages/postman-api-client/graphql-client/first-graphql-request.md deleted file mode 100644 index 3aa3efccc..000000000 --- a/src/pages/postman-api-client/graphql-client/first-graphql-request.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Making your first GraphQL query" -updated: 2022-09-15 -contextual_links: - - type: section - name: "Prerequisites" - - type: link - name: "Download and Install" - url: "https://www.postman.com/downloads/" - - type: section ---- - -Get started with GraphQL by creating a query and executing it using Postman’s echo endpoint. - -## Contents - -- [About GraphQL request](#about-graphql-request) -- [Making a GraphQL query with Postman](#making-a-graphql-query-with-postman) -- [Next steps](#next-step) - -## About GraphQL Request - -To create a GraphQL request, you need at least two things- URL and 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 make you aware of the data fields available from the server that can be included in the query. Plus, the request can also contain additional information such as Auth, 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 that has the data changing frequently, you can subscribe to the data available on different fields. This lets the server 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, Postman recommends using the Postman Desktop Agent for the best experience. See [About the Postman Agent](https://learning.postman.com/docs/getting-started/about-postman-agent/) for more information. - -1. In Postman, select **New > GraphQL Request** to open a request in a new tab. (In the Postman desktop app, you can also select **⌘+N** or **Ctrl+N**, then select **GraphQL Request**.) -2. Click on the URL bar and enter `https://graphql.postman-echo.com/graphql`. This would also load the schema using introspection. -3. In the query explorer on the left, select the `hello` field and select `person` and `name` as arguments. -4. Enter your name and age in the input boxes next to `name` and `age`. You should also see a fully formed query based on your selections on the right. -5. Hit **Query**. - -![First GraphQL Query](https://blog.postman.com/wp-content/uploads/2023/02/graphql-schema-explorer.gif) - -## Next step - -Try making a mutation and a subscription type query using the same endpoint and observe the difference in behavior. diff --git a/src/pages/postman-api-client/graphql-client/graphql-client-overview.md b/src/pages/postman-api-client/graphql-client/graphql-client-overview.md deleted file mode 100644 index 7792c7483..000000000 --- a/src/pages/postman-api-client/graphql-client/graphql-client-overview.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "GraphQL overview" -updated: 2022-01-05 -contextual_links: - - type: section - name: "Prerequisites" - - type: link - name: "Installing and updating" - url: "https://learning.postman.com/docs/getting-started/installation-and-updates/" - - type: section - name: "Additional resources" ---- - -APIs made with GraphQL allow clients to ask the server for exactly the data they need. This is enabled by a powerful query interface and a runtime to execute those queries making it easier for developers to quickly explore and experiment with the client’s functionalities. Contrary to REST, which makes your chunks of data available on multiple endpoints, GraphQL makes working with data simpler and faster with a single endpoint. Plus, GraphQL is schema driven, which means more transparency in terms of API functionality and lower dependency between teams building the client and the server. So, a client can introspect the schema from the server to get an idea about the available data fields, send queries specifying fields to retrieve or manipulate the stored data. The server does exactly what was asked from it and returns only the data requested in the query. Combining these features, GraphQL provides users with a flexible, fast and predictable API experience, making it one of the most popular API technology. - -## Work with GraphQL APIs using Postman - -Postman gives you a client interface to debug and document your API using a GraphQL request. Requests in Postman let you make API calls and view the response from the server. Using a GraphQL request, you can load a GraphQL schema to browse the documentation of what’s available from the server, create your queries, execute them, and view the response from the server. Additionally, the request interface has a visual query builder to help you create the queries faster- once the schema is loaded, you can select the fields you want to query, and Postman builds your query automatically based on your selection. You can save your GraphQL request into a collection to reuse later, document it and share it with your teammates, or publish it to the community on [Postman's public API network](https://learning.postman.com/docs/getting-started/exploring-public-api-network/). - -![GraphQL Client Interface](https://blog.postman.com/wp-content/uploads/2023/02/graphql-schema-explorer.gif) - -## Next steps - -Get started with GraphQL with the following topics: - -- [Using GraphQL Request interface](/postman-api-client/graphql-client/graphql-request-interface/) -- [Making your first GraphQL query](/postman-api-client/graphql-client/first-graphql-request/) diff --git a/src/pages/postman-api-client/graphql-client/graphql-request-interface.md b/src/pages/postman-api-client/graphql-client/graphql-request-interface.md deleted file mode 100644 index 0348e0679..000000000 --- a/src/pages/postman-api-client/graphql-client/graphql-request-interface.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: "Using GraphQL request interface" -updated: 2022-10-04 -contextual_links: - - type: section - name: "Prerequisites" - - type: link - name: "Navigating Postman" - url: "https://learning.postman.com/docs/getting-started/navigating-postman/" ---- - -GraphQL requests in Postman include a variety of tools, views and controls to help you debug and document your GraphQL API effectively and efficiently. This topic highlights the parts of the request interface and explains how to use them. - -Different sections of a GraphQL request - -## Contents - -- [Creating a new request](#creating-a-new-request) -- [Loading a GraphQL schema](#loading-a-graphql-schema) -- [Understanding parts of the request interface](#understanding-parts-of-the-request-interface) -- [Understanding the response](#understanding-the-response) -- [Creating and executing multiple queries](#creating-and-executing-multiple-queries) -- [Using the right sidebar](#using-the-right-sidebar) -- [Next step](#next-step) - -## Creating a new request - -Create a new GraphQL request by selecting the **New** button in the sidebar, which brings up the **Create new** dialog. Select **GraphQL request** from the list to open a blank gRPC request in a new tab. - -Creating a new GraphQL request - -## Loading a GraphQL schema - -You can use a GraphQL schema in your request to browse the available data fields. This makes your task of creating a query easier. Postman allows you to load a GraphQL schema using GraphQL introspection. This is the easiest way to fetch the schema directly from the server. You just need to enter the URL, and Postman loads the schema automatically. - -Adding schema to the request - -You can also choose to load a GraphQL API from Postman or import a schema from your local system to use in the request. - -## Understanding parts of the request interface - -The request interface allows you to add configurations to connect to the server and execute the query. You can define the URL, load the schema, build your query and hit Query to execute it. Based on the API requirements, you may also need to pass authorization details, additional metadata and settings along with the query. - -Different sections of the request interface - -- **URL**- Defines the endpoint where the service is hosted. While creating a new request, you can also browse through URLs you've used by selecting the URL field. This helps you create the request faster if you’re going to execute different queries with the same point. -- **Query explorer**- Once the schema is loaded, the available data fields, arguments needed to be passed, and their respective descriptions appear in this section. The schema query also doubles up as an interactive visual query builder allowing you to select individual fields and arguments to build your query. -- **Query builder**- The place to explore and build your query, mutation, fragment, and subscriptions -- **Response**- Where the response from the highlighted query/mutation/subscription is displayed -- **Variables**- GraphQL allows you to pass variables as arguments for values that are defined dynamically in the client. You can use those variables in the query and define their values separately using the variables section. -- **Authorization**- Pass credentials that the server would use to authorize the connection here. You can choose from a list of auth types including API Key, Basic auth, and Bearer token etc. Learn more about [authorizing requests](https://learning.postman.com/docs/sending-requests/authorization/). -- **Headers**- Pass additional headers with the request in the form of key-value pairs. The client uses these headers to provide more information about the call to the server. -- **Schema**- The schema tab lets you configure a GraphQL schema to make the client aware of the data fields available from the server. A GraphQL schema can be loaded directly using the URL through introspection. You can also choose to use a GraphQL API from the same workspace or import a GraphQL schema from your local system. -- **Scripts**- Postman has a powerful scripting environment that allows you to add JavaScript code (scripts) in your GraphQL requests. You can use scripts to write API tests, debug your requests by logging to [Postman Console](https://learning.postman.com/docs/sending-requests/troubleshooting-api-requests/), or dynamically read or update the values of [variables](https://learning.postman.com/docs/sending-requests/variables/). -- **Query button**- Once you have defined the URL and built the query, you can hit **Query** to execute it. Once the query is executed, the server sends back a response with the requested data. -- **Save button**- Saves the request into a collection so that you can reuse it later or document and share it with others. - -## Understanding the response - -When you execute a query, the server gives back the appropriate response that appears in the response area. - -Different sections of the response interface - -The response section has the following items: - -- **Response body**- This section shows the data returned by the server for the fields mentioned in the query. -- **Wrap text button**- Selecting this button adjusts the width of the response body according to the width of the response area, making it easier to read wider responses without scrolling horizontally. -- **Search**- Look for specific elements within the response using the **Search** button. -- **Headers**- Headers returned by the server typically consists of additional information about the execution. -- **Test results**- The results for assertions you write in the Scripts section appear here. Based on the test script, the results can be one of three types: Passed, Failed, and Skipped. - -### Multiple responses - -While executing a subscription type query that returns multiple responses over a persistent connection, the response area shows these responses as a stream. - -Different sections of the response stream - -- **Response stream**- The response stream has the request and the responses arranged in reverse chronological order (latest appears on the top). -- **Expand/collapse response**- You can take an in-depth look at the response content by expanding it within the response stream. -- **Search for response**- You can use the high-level search input to search for particular responses. -- **Filter**- Adjust the view based on the type of messages using the message filter. Instead of all messages, you can choose to view the ones Sent from the client or Received from the server. -- **Clear**- The **Clear** button hides all the messages exchanged from the view, cleaning up the response area so that you can focus on the new messages. You can restore the messages using the **Restore** button in the hidden view. - -## Creating and executing multiple queries - -The GraphQL request interface allows you to create multiple queries in the query builder and execute them one at a time. You can select a query from the query editor and hit **Query**. This would execute only the selected query and return the appropriate response. - -Sending multiple queries using the query editor - -You can also use the send button dropdown to browse through the queries and select one to execute. - -Sending multiple queries using the Query button - -## Using the right sidebar - -The right sidebar gives you access to more tools and information like documentation, commenting, and request details. Open a GraphQL request, and then select an option in the right sidebar: - -- **Request documentation**- Select the documentation icon to view description of a request. You can add description by selecting the edit icon next to the description, then writing your content using [Postman's built-in editing tools](https://learning.postman.com/docs/publishing-your-api/authoring-your-documentation/). -- **Comments**- Select the comments icon to collaborate with your teammates as you work on an API. You can use `@` to tag others to ask a question, give feedback, and discuss your API. -- **Request information** - Select the information icon to view more details about a request, like the request ID and creation date. - -## Next step - -After you understand all the basic interface elements, try [making your first GraphQL query](/postman-api-client/graphql-client/first-graphql-request/). diff --git a/src/pages/postman-api-client/mqtt-client/first-mqtt-request.md b/src/pages/postman-api-client/mqtt-client/first-mqtt-request.md deleted file mode 100644 index a57b518c5..000000000 --- a/src/pages/postman-api-client/mqtt-client/first-mqtt-request.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "Creating your first MQTT request" -updated: 2023-09-15 -contextual_links: - - type: section - name: "Prerequisites" - - type: link - name: "Download and Install" - url: "https://www.postman.com/downloads/" - - type: section ---- - -Connect to a public broker, subscribe to topics and publish messages. - -## Contents - -- [Create an MQTT request](#create-an-mqtt-request) -- [Connecting to a broker with Postman](#connecting-to-a-broker-with-postman) -- [Subscribing to topics](#subscribing-to-topics) -- [Publishing messages](#publishing-messages) -- [Using response visualizer](#using-response-visualizer) - -## Create an MQTT request - -In Postman, select **New > MQTT** to create a new request. (In the Postman desktop app, you can also select **⌘+N** or **Ctrl+N**, then select **MQTT**). - -----{Image: Create MQTT request}---- - -## Connecting to a broker with Postman - -To connect to an MQTT service, you need a broker URL. In this example, we will use the public broker `test.mosquitto.org`. You can also use any other public broker or a broker hosted on your local machine. - -1. Enter `test.mosquitto.org` as the request **URL**. -2. Click on the **Connect** button to connect to the broker. - -A message in the response area indicates that you are connected to the broker. - -----{Image: Connect to broker}---- - -> If you are using the Postman web app, Use the Postman desktop agent to connect to an MQTT broker. See [About the Postman Agent](https://learning.postman.com/docs/getting-started/about-postman-agent/) for more information. - -## Subscribing to topics - -While being connected to the broker, go to the **Topics** tab. This interface allows you to list down and document multiple topics, and subscribe to them. - -1. In the **Topics** column, enter `my-toys` as the topic name. -2. Click on the **Subscribe** button to subscribe to the topic. - -You should see a message in the response area indicating that you are subscribed to the topic. - -----{Image: Subscribe to topic}---- - -## Publishing messages - -You can use the **Message** tab to compose and send messages to the broker. - -1. In the **Message** tab, enter `{"age": 2, "number of toys": 5}` as the message. -2. Enter `my-toys` as the topic name. -3. Click on the **Send** button to publish the message. - -You should see an outgoing message in the response area indicating that the message was published. Since you have already subscribed to the topic, `my-toys`, you should also see an incoming message with the same body. Go ahead and send a few more messages counting the number of toys you had growing up. - -----{Image: Publish message}---- - -## Using response visualizer - -Now that you have subscribed to a topic and published a few messages, you can use the response visualizer to view the messages in a more comprehensible format. - -1. Switch to the **Visualization** tab in the response area. You should be able to see the messages for `age` field visualized as a line chart. -2. Click on the field name dropdown to select the field you want to visualize. -3. Click on the ----{Image: + icon}---- icon to add more fields to the chart and view the changes in their values together. -4. Click on the ----{Image: chart icon}---- next to any of the field names to change the chart type. - -The visualization changes in real time as you keep receiving newer messages for the same topic. - -----{Image: Visualize response}---- - -## Next step - -Try subscribing to multiple topics at once and publishing messages to them. diff --git a/src/pages/postman-api-client/mqtt-client/mqtt-client-overview.md b/src/pages/postman-api-client/mqtt-client/mqtt-client-overview.md deleted file mode 100644 index dda26a802..000000000 --- a/src/pages/postman-api-client/mqtt-client/mqtt-client-overview.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "MQTT overview" -updated: 2023-09-15 -contextual_links: - - type: section - name: "Prerequisites" - - type: link - name: "Installing and updating" - url: "https://learning.postman.com/docs/getting-started/installation-and-updates/" - - type: section - name: "Additional resources" ---- - -MQTT (Message Queuing Telemetry Transport) is a messaging protocol for the Internet of Things (IoT). Its usage spans from simple devices for home automation and wearables, to automating large scale industrial machineries. It is a lightweight technology modeled on the publish/subscribe pattern where clients connected to a single broker can publish messages to different topics and subscribe to topics to receive messages from other connected clients. The messages are transferred with low bandwidth usage, low power consumption, and efficient distribution of information to one or many receivers; all adding to the popularity of MQTT. - -## Work with MQTT APIs using Postman - -Postman provides you with a client interface to debug your MQTT based APIs. You can create a new MQTT request, connect to a broker, subscribe to topics, publish messages, and view the messages received from the broker. You can save your MQTT request into a collection to reuse later, document it and share it with your teammates, or publish it to the community on [Postman's public API network](https://learning.postman.com/docs/getting-started/exploring-public-api-network/). - -------{Image: MQTT Client Interface}------ - -## Next steps - -Get started with MQTT with the following topics: - -- [Using MQTT Request interface](/postman-api-client/mqtt-client/mqtt-request-interface/) -- [Making your first MQTT request](/postman-api-client/mqtt-client/first-mqtt-request/) diff --git a/src/pages/postman-api-client/mqtt-client/mqtt-request-interface.md b/src/pages/postman-api-client/mqtt-client/mqtt-request-interface.md deleted file mode 100644 index f239b2a67..000000000 --- a/src/pages/postman-api-client/mqtt-client/mqtt-request-interface.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: "Using MQTT request interface" -updated: 2023-09-15 -contextual_links: - - type: section - name: "Prerequisites" - - type: link - name: "Navigating Postman" - url: "https://learning.postman.com/docs/getting-started/navigating-postman/" ---- - -MQTT requests in Postman include a variety of tools, views and controls to help you debug and document your MQTT APIs. This topic highlights the parts of the request interface and explains how to use them. - -----{image: different sections of a MQTT request}---- - -## Contents - -- [Creating a new MQTT request](#creating-a-new-MQTT-request) -- [Understanding parts of the request interface](#understanding-parts-of-the-request-interface) -- [Understanding the response](#understanding-the-response) -- [Using the right sidebar](#using-the-right-sidebar) - -## Creating a new MQTT request - -Create a new MQTT request by selecting the **New** button in the sidebar, which brings up the **Create new** dialog. Select **MQTT** from the list to open a blank MQTT request in a new tab. - -----{image: creating a new MQTT request}---- - -You can also create a new MQTT request by clicking on the **New Tab** button (----{image: new tab button}---- icon in the tabs bar) and clicking on the **Request type** button next to the request name (Untitled Request) and selecting **MQTT** from the list. - -----{image: creating a new MQTT request from the tabs bar}---- - -## Understanding parts of the request interface - -The request interface lets you add configuration to connect to an MQTT broker, subscribe to topics, and publish messages. Additionally, you can add last will details, authorization details, custom properties, and settings along with the request. - -----{image: different sections of the request interface}---- - -- **URL**- This is where you enter the broker's address; e.g. `test.mosquitto.org`. Some MQTT services also require you to define a port number. You can define a port number in the URL by appending the port number to the URL. For example, `test.mosquitto.org:1883`. - > For connecting to the broker over TLS, you need to use `mqtts://` as your URL scheme. For example, `mqtts://test.mosquitto.org`. - - **MQTT Version**- Every MQTT version has some distinctions in terms of the protocol features. Postman supports 2 major versions of MQTT; 3.1.1 and 5.0. Version 5.0 is selected by default. - - **Client ID**- Client ID is an identifier differentiating each client connected to the broker. By default, Postman generates a random client ID for each request. But you can override this by clicking on the **Client ID** button and entering a custom client ID. -- **Message**- This is where you compose and Publish messages to the broker. You can write your message in the text area, enter a topic name and click on **Send** to publish the message. - - **Properties**- You can add custom properties to your message. These properties are sent along with each message to the broker. - - **Message type**- You can define the message type as **Text**, **JSON**, **Base64**, or **Hexadecimal** for Postman to convert the message to the selected type before sending it to the broker. - - **Topic**- You can define the topic name for the message here. The topic name is used by the broker to route the message to the appropriate subscribers. - - **QoS**- QoS defines the guarantee of delivery for the message. You can configure the Quality of Service (QoS) level for the message by clicking on the ----{image: Options icon}---- icon selecting a QoS level. - - **Retain**- Retain is a flag that asks the broker to retain the last message sent on the topic and send it to the new subscribers even if they join the network after the message was sent from the client. You can configure the retain flag for the message by clicking on the ----{image: Options icon}---- icon and toggling the **Retain** switch. - - **Send**- Once you have configured the payload, click on the **Send** button to publish the message to the broker. -- **Topics**- This is where you can list down and document multiple topics, and subscribe to them. You can also configure the QoS level for each topic listed. -- **Last Will**- Last Will is a message that is sent by the broker to the subscribers when the client disconnects from the broker. You can configure the Last Will message by going to the **Last Will** tab, entering the message, and configuring additional settings such as topic name, QoS level, and retain flag. You can also configure thw will delay interval by clicking on the ----{image: Options icon}---- icon and entering the delay interval in milliseconds. -- **Authorization**- Authorize your connection with Basic Auth. You can pass your credentials in the form of username and password to the broker using the **Authorization** tab. -- **Properties**- You can add custom properties to your request. These properties are sent while connecting to the broker. -- **Settings**- You can configure additional settings for your request by going to the **Settings** tab. You can configure the request timeout, enable/disable SSL certificate verification, clean session, and auto reconnect etc. - -## Understanding the response - -When you connect to the broker, the response area creates a message stream showing the published and received messages to different topics in a single session (until you click on **Disconnect**). - -----{image: response area}---- - -- **Messages**- The message stream shows the published and received messages in a timeline. You can expand the message to view the message details such as topic name, QoS level, retain flag, and message type. You can search for specific messages using the search bar, filter messages by received and sent and clear the message stream using the **Clear Messages** button. -- **Visualization**- The **Visualization** tab shows the message stream in a graphical format, a more comprehensible way to view telemetry data. The interface is divided into multiple windows per topic you have received messages for. For JSON responses, the values for the first field are plotted on the graph. You can change the selected field, and add more fields to compare the values side by side. You can also change the visualization style from line to bar chart. - -----{image: visualization tab}---- - -## Using the right sidebar - -The right sidebar gives you access to more tools and information like documentation, commenting, and request details. Open a GraphQL request, and then select an option in the right sidebar: - -- **Request documentation**- Select the documentation icon to view description of a request. You can add description by selecting the edit icon next to the description, then writing your content using [Postman's built-in editing tools](https://learning.postman.com/docs/publishing-your-api/authoring-your-documentation/). -- **Comments**- Select the comments icon to collaborate with your teammates as you work on an API. You can use `@` to tag others to ask a question, give feedback, and discuss your API. -- **Request information** - Select the information icon to view more details about a request, like the request ID and creation date. - -## Next steps - -[Create your first MQTT request](/postman-api-client/mqtt-client/first-mqtt-request/) diff --git a/src/pages/postman-api-client/websocket-client/websocket-client-overview.md b/src/pages/postman-api-client/websocket-client/websocket-client-overview.md deleted file mode 100644 index 7d2881e73..000000000 --- a/src/pages/postman-api-client/websocket-client/websocket-client-overview.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: "Using WebSocket Requests" -order: 38 -updated: 2021-10-11 -page_id: "websocket" -search_keyword: "WebSocket, websockets, WebSocket requests, Socket.IO" -contextual_links: - - type: section - name: "Prerequisites" - - type: link - name: "Installing and updating" - url: "https://learning.postman.com/docs/getting-started/installation-and-updates/" - - type: section - name: "Additional Resources" - - type: subtitle - name: "Videos" - - type: link - name: "WebSocket Requests | Postman Level Up" - url: "https://youtu.be/H-7EZVj9D-k" - - type: subtitle - name: "Blog Posts" - - type: link - name: "Save and Document WebSocket Requests in Collections" - url: "https://blog.postman.com/save-and-document-websocket-requests-in-collections/" - - type: link - name: "Postman Supports Socket.IO" - url: "https://blog.postman.com/postman-now-supports-socket-io/" - -warning: false - ---- - -The WebSocket protocol provides a way to exchange data between a client and server over a persistent connection. The data can be passed in both directions with low latency and overhead, and without breaking the connection. WebSockets provide a bidirectional, full-duplex communications channel that operates over HTTP through a single TCP socket connection. This means the server can independently send data to the client without the client having to request it, and vice versa. - -In Postman you can create a WebSocket request with a server, and use it to send and receive messages across the WebSocket connection. - -### About Socket.IO - -In addition to raw WebSocket connections, Postman also supports Socket.IO connections. Socket.IO is one of the most popular libraries to enable event-driven, bidirectional, real-time communication between clients and servers. It uses WebSocket as its transport layer. Many developers use Socket.IO in combination with HTTP APIs, and Postman enables you to switch between the two paradigms at will. - -## Contents - -* [Creating WebSocket requests](#creating-websocket-requests) -* [Sending messages](#sending-messages) -* [Viewing messages](#viewing-messages) -* [Using variables in requests and messages](#using-variables-in-requests-and-messages) -* [Adding request details](#adding-request-details) -* [Saving requests](#saving-requests) -* [Documenting collections and requests](#documenting-collections-and-requests) -* [Other Socket.IO Notes](#other-socketio-notes) -* [Troubleshooting WebSocket Requests](#troubleshooting-websocket-requests) - -## Creating WebSocket requests - -You can create a WebSocket request from the sidebar in Postman. - -1. Select __New__ > __WebSocket Request__ to open a new tab. (In the Postman Desktop app, you can also select **⌘+N** or **Ctrl+N**.) - - [![New Screen](https://assets.postman.com/postman-docs/new-request-websocket-v91.jpg)](https://assets.postman.com/postman-docs/new-request-websocket-v91.jpg) - -1. In the upper left of the request tab, select either **Raw** for a raw WebSocket request, or **Socket.IO** for a Socket.IO request. -1. Enter the WebSocket server URL. A WebSocket URL begins with `ws://` or `wss://`. - - [![WebSocket server URL](https://assets.postman.com/postman-docs/websocket-server-url-v11.jpg)](https://assets.postman.com/postman-docs/websocket-server-url-v11.jpg) - -1. Select **Connect**. -1. To disconnect your WebSocket request's connection, select **Disconnect**. - -> If you are using Postman for Web, you must use the Postman Desktop Agent. See [Using Postman on the web](/docs/getting-started/installation-and-updates/#using-postman-on-the-web) for more information. - -## Sending messages - -After making a WebSocket connection, you can use the editor pane to compose and send messages. - -[![WebSocket message editor](https://assets.postman.com/postman-docs/websocket-message-editor.jpg)](https://assets.postman.com/postman-docs/websocket-message-editor.jpg) - -In the bottom left corner of the editor, you can select the format of your message: **Text**, **JSON**, **XML**, **HTML**, or **Binary**. If you select **Binary**, you can then select **Base64** or **Hexadecimal**. The editor has syntax highlighting according to the selected format. You can also select **{}** to beautify JSON, XML, or HTML messages. - -When you have finished composing your message, select **Send**. The sent message will remain in the window, in case you want to change it and re-send, or save it. - -### Saving messages - -You can also save composed messages, then re-send them later. To the right of the editor pane is a collapsible pane for **Saved Messages**. - -To save a message: - -1. Compose a message, as described above. -1. Select **Save Message**. -1. The message title ("New Message" by default) is now editable. Enter a new title and press Return. - -To load a saved message: - -1. Open the **Saved Messages** pane to the right of the editor pane. -1. Select a saved message. It will be loaded into the editor pane. -1. You can then send the message, or edit it and select **Save Message** to save the changes. Select **Discard Changes** to remove them. - -You can also create a new message from the **Saved Messages** pane by selecting Edit icon **Compose Message**. - -To rename, duplicate, or delete a saved message, select the more actions icon More actions icon and then select **Rename**, **Duplicate**, or **Delete**. - -### Adding Socket.IO event names and arguments - -Sending events with a Socket.IO connection includes the ability to add event names and arguments. This enables you to listen to only specific events. - -For a Socket.IO connection, you can enter an event name to publish next to **Send**. If you select **Send** without entering a name, the default name `message` will be used. - -There is also an **Acknowledgement** option; when selected, the server will acknowledge that it has received the message. - -Socket.IO event name - -You can also add arguments to a Socket.IO connection. In the bottom left of the editor pane, select **+ Arg**. A sidebar will open to the left of the editor pane adding an argument and a new editor pane for the argument's message. Hover over an existing argument and select **x** to delete it. The workflow to inspect each argument's message is similar. - -Socket.IO arguments - -## Viewing messages - -The **Messages** pane displays a list of messages for the WebSocket connection, including incoming, outgoing, and network messages. - -At the top of the message pane is a connection details badge. It shows if the connection is connecting, connected, disconnecting, or disconnected. Hover over the badge to show details on the connection. Select the arrow next to the badge to show or hide messages. - -[![WebSocket messages](https://assets.postman.com/postman-docs/websocket-messages.jpg)](https://assets.postman.com/postman-docs/websocket-messages.jpg) - -Above the message display are the following controls: - -* Search control - Enter a search term to display only messages containing the term. Select Close icon to end the search. -* Message type list - Select if you want to view all messages, or only incoming or outgoing messages. -* Trash - Select the delete icon Delete icon to clear all messages. - -The following are displayed for each message: - -* If you hover over a message, a check box is displayed. Select the check boxes for two messages, and the time difference between the messages will be displayed. Select **Deselect** to remove the time display. - [![WebSocket time difference](https://assets.postman.com/postman-docs/websocket-time-difference.gif)](https://assets.postman.com/postman-docs/websocket-time-difference.gif) -* Select the arrow next to a message to expand or collapse it. -* The time is displayed as your local time. -* If you hover over the time of a raw Socket.IO message, an information icon is displayed. Hover over it for the time, MIME type, and size of the message. -* If you hover over the time, a copy icon is also shown. Select this to copy the message to your clipboard. - -In an expanded message: - -* Select **Text**, **HTML**, **JSON**, or **XML** to change the formatting of the message. -* Select **Wrap Line** to add or remove line wraps. -* Select **Show Hexdump** or **Show Message** to show the message in hex or text. -* Use the search control to search the body of the message. -* Hover over a line number and select the arrow to expand or collapse message blocks. -[![WebSocket message body](https://assets.postman.com/postman-docs/websocket-message-body.jpg)](https://assets.postman.com/postman-docs/websocket-message-body.jpg) - -### Event listening in Socket.IO - -In Socket.IO, you have the ability to listen to specific events. The **Messages** pane will only display the received events for which you've added listeners. Events will be color-coded by event to make them easier to find. - -To the left of the **Messages** pane in a Socket.IO request is a **Listeners** panel of listener events. To listen to a new event, enter the name of an event and select **+** to add it. Select the toggle next to an event to turn listening on or off for that event. If you hover over the toggle, you can delete the event listener. - -[![Socket.IO message body](https://assets.postman.com/postman-docs/socketio-message-body.jpg)](https://assets.postman.com/postman-docs/socketio-message-body.jpg) - -Messages will indicate if they have multiple arguments. When you expand the message, it will have tabs for each argument. - -[![WebSocket message body](https://assets.postman.com/postman-docs/socketio-message-with-args.jpg)](https://assets.postman.com/postman-docs/socketio-message-with-args.jpg) - -Prior to making a connection, you can also add events in the **Events** tab above the editor pane. This enables you to add a description for each event and select if the event will listen when the connection is made. - -## Using variables in requests and messages - -You can use Postman variables in the URL of a WebSocket connection or the body of a message. For example, you could create a variable named `my_host`, set the value to `example.com` and then use a URL of `ws://{{my_host}}/api/example`. If you enter `{{` in either the URL field or message editor, you can autocomplete your variables. - -See [Using variables](/docs/sending-requests/variables/) for more information on how to use variables. - -## Adding request details - -You can add details to your request, for example to send additional parameters and headers. You can also configure the connection. Select the **Params**, **Headers**, or **Settings** tab above the editor pane to make changes. - -> You can't change request details while you are connected. You must make any changes before you connect, or select **Disconnect** to stop the current connection. - -### Sending parameters - -On the **Params** tab, add any parameters you would like to append to the WebSocket URL. This works similarly to [sending parameters](/docs/sending-requests/requests/#sending-parameters) in a REST request. - -### Configuring headers - -On the **Headers** tab, enter any headers you would like to send with your message. This works similarly to [configuring request headers](/docs/sending-requests/requests/#configuring-request-headers) in a REST request. - -### Configuring request settings - -The following settings can be configured for your WebSocket request: - -| Setting | Description | -|-----|-----| -| Client version | The Socket.IO client version to be used to connect with the server. (Socket.IO only)| -| Handshake path | The server-side path that will be captured. (Socket.IO only) | -| Handshake request timeout | How long the handshake request will wait before timing out, in milliseconds. This is reset after every redirection. | -| Reconnection attempts | The maximum number of reconnection attempts before disconnecting. | -| Reconnection intervals | The period in milliseconds between reconnection attempts. | -| Maximum message size | The maximum allowed message size, in megabytes. To receive messages of any size, set this to 0. (Raw WebSocket only)| - -## Saving requests - -You can save your WebSocket requests into a collection. This enables you to reuse requests, share them with other team members, and add documentation to the collection of requests. - -To save a request: - -1. In the upper right of the request tab, select **Save**. -1. In **Save request**, under **Save to**, select a collection, or select **Create collection**. (Note that there are limitations to WebSocket requests in collections. Keep reading for more information.) -1. If you are creating a new collection, enter a name and select **Create**. -1. Select **Save**. - -Postman will display your collection and saved request in **Collections** in the sidebar: - -Collection sidebar - -Because WebSocket requests have different features than HTTP requests, when they're added to a collection, it causes the collection to be in a “beta” state with certain limitations. - -When in this state, a collection can only contain WebSocket requests. It can't contain folders or HTTP requests, and you can't move requests into or out of such a collection. - -Collections containing WebSocket requests support the use of documentation and variables. Other features related to collections aren't supported, such as collaboration, version control, or scripting. - -## Documenting collections and requests - -You can add documentation to your collection or requests to give it a summary, and add any notes or details you want to share with others. Documentation will also be automatically included for the request's URL, parameters, settings, and all saved messages. - -To document a WebSocket request: - -1. Open the request. -1. Select the documentation icon Documentation icon in the context bar. -1. Select the edit icon Edit icon next to the description. -1. Author your description using [Markdown](/docs/publishing-your-api/authoring-your-documentation/#authoring-descriptions-in-markdown). -1. When you're finished, select **Save** to save your documentation. If you ever need to make changes, you can edit the description again. - -Documenting a collection is similar, but the description is on the **Overview** tab of the collection. Select the edit icon Edit icon next to the description, write a summary, and select **Save**. - -## Other Socket.IO notes - -Socket.IO typically uses WebSockets as its transport layer, but sometimes uses HTTP "long-polling" as a fallback when WebSockets can't be used. Postman doesn't support long-polling mode in Socket.IO. - -## Troubleshooting WebSocket requests - -You can use the console to debug issues with a WebSocket connection. To open the console and view log messages, select Console icon **Console** in the Postman footer. - -For more information on using the console, see [Troubleshooting requests](/docs/sending-requests/troubleshooting-api-requests/). From 96b5e9afac3b64fb88935ef0d500d19696b7ba8d Mon Sep 17 00:00:00 2001 From: Jonathan Konrath <80709817+jkonrath-postman@users.noreply.github.com> Date: Thu, 19 Oct 2023 10:53:32 +0530 Subject: [PATCH 2/2] Add redirects --- redirects.json | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/redirects.json b/redirects.json index b623f42ea..900781ae9 100644 --- a/redirects.json +++ b/redirects.json @@ -2,5 +2,33 @@ { "from": "/postman-flows/getting-started/flows-overview/", "to": "https://learning.postman.com/docs/postman-flows/flows-intro/flows-overview/" + }, + { + "from": "/postman-api-client/graphql-client/graphql-client-overview/", + "to": "https://learning.postman.com/docs/sending-requests/graphql/graphql-overview/" + }, + { + "from": "/postman-api-client/graphql-client/graphql-request-interface/", + "to": "https://learning.postman.com/docs/sending-requests/graphql/graphql-client-interface/" + }, + { + "from": "/postman-api-client/graphql-client/first-graphql-request/", + "to": "https://learning.postman.com/docs/sending-requests/graphql/graphql-client-first-request/" + }, + { + "from": "/postman-api-client/websocket-client/websocket-client-overview/", + "to": "https://learning.postman.com/docs/sending-requests/websocket/websocket/" + }, + { + "from": "/postman-api-client/mqtt-client/mqtt-client-overview/", + "to": "https://learning.postman.com/docs/sending-requests/mqtt-client/mqtt-client-overview/" + }, + { + "from": "/postman-api-client/mqtt-client/mqtt-request-interface/", + "to": "https://learning.postman.com/docs/sending-requests/mqtt-client/mqtt-request-interface/" + }, + { + "from": "/postman-api-client/mqtt-client/first-mqtt-request/", + "to": "https://learning.postman.com/docs/sending-requests/mqtt-client/first-mqtt-request/" } ] \ No newline at end of file