Postman Tutorial: Disqus REST API #1

Postman: Disqus API Case Study (1) – List Discussions and Get Thread Details

What’s Postman

Postman Logo

Postman is a great tool when trying to test RESTful APIs. It offers a user-friendly graphical user interface, which streamlines making HTML requests to test an APIs functionality without the hassle of writing a bunch of code. With the Postman, all you need to do is copy an API endpoint URL to the address bar, select the HTTP request method on the dropdown box to its left, list the query params in an easy-to-read table format or specify those in a JSON format, and hit send. Then, the Postman pretty prints the API response data in JSON. It’s that simple!

Because of this, it is an essential tool for the Internet of Things (IoT) projects. It is common to employ various APIs or even build one for the connection between IoT devices and web applications. For example, the pipelines for getting the status of devices and servers as well as sending messages and notifications to PCs and phones. You can use the Postman to test what data are sent to or received from the APIs.

So, let’s start to do some exercises to study how to fetch data from a public API service using the Postman. In the following sections, you will practice it with Disqus REST API, which enables you to communicate with the data stored on the Disqus comment system. If you’re new to Postman, here is a video series for you to can learn the basics about that.

[ Back to Top ]


Access Disqus REST API with Postman

Disqus is a comment system for readers to have discussions about online content, and the stack of comments on a web page is called a discussion thread. The Disqus comments can be an interesting data source for trend statistics and natural language analysis. You can build an application to consume and digest the information by getting the data from the API.

With the Postman, you can quickly test the API endpoints and your parameters and then generate the codes for your prototype app. This article contains two beginner-level exercises. The first one is to get the discussion threads of a specific Disqus forum. The second one is to try querying the thread details by a thread ID, an identifier, or a source URL, respectively.

Before that, you have to prepare the following:

  1. Get your Disqus API key
  2. Create a new workspace in Postman
  3. Create a new environment to store variables in Postman

Preparations

Get your Disqus API key

The Disqus API works over the HTTP protocol. It supports both server-side (secret key) methods, as well as a public-facing JavaScript API using your public key and HTTP referrer checks. If you are using the public-facing JavaScript API, you will need to send api_key with your public API key value. To obtain your key, you have to go to register an application on this page (https://disqus.com/api/applications/).

Postman: Disqus API Case Study (1) - List Discussions and Get Thread Details 1
  1. Click on the Register new application button.
Postman: Disqus API Case Study (1) - List Discussions and Get Thread Details 2
  1. In the registration form, fill in the name and description of your application as well as your organization and website.
Postman: Disqus API Case Study (1) - List Discussions and Get Thread Details 3
  1. In the Application Settings, scroll to the Authentication section to select the scope for the Disqus API access.
Postman: Disqus API Case Study (1) - List Discussions and Get Thread Details 4
  1. Go the Settings > Domains, add the domains that will access the API for security check.

After that, you can find the API key for your registered application in its Details page.

Postman: Disqus API Case Study (1) - List Discussions and Get Thread Details 5

Create new personal workspace in Postman

Open the Postman on your PC. I suggest you start with a new workspace. In this way, you can isolate your projects and prevent override variables when you are unfamiliar with Postman. You can create unlimited Personal workspaces. To create a new workspace, select the workspace dropdown menu at the top and center of Postman, and click on Create New. Enter the name, such as Disqus API, for you to identify your workspaces.

Postman: Disqus API Case Study (1) - List Discussions and Get Thread Details 6
Create a new workspace

Create new environment to store API key in Postman

When you access APIs, it often includes sensitive data values, such as API keys and credentials. You can prevent accidentally share your values by making use of environments to store the values as environment variables. To use the Disqus API, create a variable called api_key and copy your Public Key as its value.

Postman: Disqus API Case Study (1) - List Discussions and Get Thread Details 7
The setting of the postman environment called Disqus Env

[ Back to Top ]


Exercise 1 – Get Discussions using Disqus API endpoint

forum/listThreads

Documentation: https://disqus.com/api/docs/forums/listThreads/

The forum/listThreads endpoint returns a list of threads within a forum sorted by the date created. It does not require authentication. Only two parameters are necessary: api_key and forum. Alternatively, you can use the threads/list endpoint to query a list of threads by forum, category, author, and more. Both endpoints return the data in the same structure. Use the following data to set up the request of the forum/listThreads endpoint:

MethodGET
URLhttps://disqus.com/api/3.0/forums/listThreads.json
api_key{{api_key}}
The Public Key stored in your environment
forumA Disqus shortname

Make sure that you select the right environment to apply the environment variable. The request query should look like the screenshot below.

Postman: Disqus API Case Study (1) - List Discussions and Get Thread Details 8
Response
JSON

The JSON-formatted data above is an example response of the forum/listThreads endpoint. It contains only one thread, since the parameter limit=1 was added to restrict the number of results. To load more results, you can copy the value of cursor.next from the response and carry out pagination with cursor in the query parameters.

[ Back to Top ]


Exercise 2 – Get Disque Thread Details

threads/details

Documentation: https://disqus.com/api/docs/threads/details/

The threads/details endpoint returns the information of a single thread. It provides three ways to look up a thread:

Looks up a thread by ID

MethodGET
URLhttps://disqus.com/api/3.0/forums/listThreads.json
api_key{{api_key}}
The Public Key stored in your environment
threadA Disqus Thread ID

Looks up a thread by identifier and Disqus shortname

MethodGET
URLhttps://disqus.com/api/3.0/forums/listThreads.json
api_key{{api_key}}
The Public Key stored in your environment
thread:identA Disqus Identifier
forumA Disqus Shortname

Looks up a thread by link and Disqus shortname

MethodGET
URLhttps://disqus.com/api/3.0/forums/listThreads.json
api_key{{api_key}}
The Public Key stored in your environment
thread:linkSource URL
forumA Disqus Shortname
Response
HTML

[ Back to Top ]


Generate Python requests code snippet using Postman

Postman: Disqus API Case Study (1) - List Discussions and Get Thread Details 9
Click on “Code” to generate code snippet

You can apply the request to other platforms by generating code snippets using Postman. After testing the API request, click on “Code” below the Send and Save buttons. A dialog will show up for you to select programming languages and preview the generated code. The following screenshot is an example code snippet for Python.

Postman: Disqus API Case Study (1) - List Discussions and Get Thread Details 10

To test the Python code, you can open a Jupyter notebook on Google Colab. Copy the code to the notebook and run by pressing Ctrl + Enter. It should return the same API response as in Postman.


Find out more

Note: This post includes affiliate links for which I may make a small commission at no extra cost to you when you make a purchase.


Wrap up

Based on this case study, you should understand how to access public data from the Disqus REST API using Postman. First, start with register an application on Disqus to get your API keys. Second, create a workspace and environment in Postman for the project. Third, build and send a GET request with the Postman GUI (such as enter an endpoint URL and query params according to the Disqus API Documentation). You can apply this know-how to hot topic detection and tracking.

Keep on reading:

If you like this post, please share it with your Facebook and Twitter. You might also support me by donating via Ko-fi.

scroll to top