Getting started using Postman with the Discourse API

[supermathie (Michael Brown)]

Summary

Postman is a way to easily construct and test requests against an API.

Configuring with Discourse

1. After opening Postman, click Create Workspace:

   

2. Choose Blank workspace and click Next.

3. Title it Discourse API and select Create:

   

4. Click Collections:
   

   

5. Click Import:
   

   

6. Paste https://docs.discourse.org/openapi.json (which is the “Download” URL shown on docs.discourse.org):
   

   

7. Choose to import as a Postman Collection:
   

   

Create a new Environment

1. Click on Environments and Create Environment. This will hold variables specific to the instance you’re testing. For this example, we’ll use try.discourse.org.

   • add a new variable: defaultHost with the value try.discourse.org:
   • select the try.discourse.org environment from the ⑤ Environment dropdown
   

Hello World!

Let’s try a request!

1. Select Collections → categories.json → Retrieves a list of categories and click Send. You should see the result:
   
   

Add authentication to requests

To use the API with API key authentication:

1. Add the following variables to this or a new environment:

   • api-username
   • api-key
   
   
   (their values must of course be valid for the site you are querying)

2. Add a script to the collection
   Select Collections → Discourse API Documentation → Scripts → Pre-request and paste the following:

   pm.request.headers.add({
       key: "api-key",
       value: pm.variables.get("api-key")
   })
   pm.request.headers.add({
       key: "api-username",
       value: pm.variables.get("api-username")
   })