How to try the web services using Postman

What is Postman? And why should I use it?

Postman is a desktop app that allows you to send HTTP requests to an API. Many parameters can be set and scripted for each request. Which makes it the perfect tool to try the Teach on Mars web services.

Sometimes, reading a documentation is a bit too abstract, and some client-specific configuration might induce variations in the web services responses. With this tool, you will be able to run some tests with different parameters and obtain representative responses with the true client configuration.

Step by step how to

Download and install postman

Got to postman.com and follow the instructions.

Open the Teach on Mars web services collection

1. Open the Teach on Mars Web Services documentation in your web browser.
2. Click on the Run in Postman button in the top right hand corner.
   
3. Open the Postman app
   

 You now have your Postman app opened with the collection of Teach on Mars web services imported.

Configure your environment

First, download the environment blueprint, and import it like this:

1. Open the Manage Environments menu

2. Choose Import in the menu

3. Select the TOMEnvironmentBlueprint.postman_environment.json file you have just downloaded

4. Click on the new environment called Teach on Mars Env Blueprint

5. Change the name of the environment to something that suits your configuration and fill in the values that you have been given by your project manager. Then click Update.

Values should look like that:

6. Select your custom environment in the environment menu in the top right hand side of the interface

Run your first request

In order to make sure that your Postman project is working fine  with the configured environment, let's try and send one simple request: one to fetch learners in the Mission Center.

1. Open the collection and the Learners management folder in the side menu, then select the request named Fetch learner

2. Click on the big blue Send button on the right

3. The result of the request is displayed below

If you see something like that (status: 200), you're all good.

If not, well ... the next section is for you.

Troubleshooting

Message: Could not get any response

How to fix:

• Check that you have filled the environment values properly (especially TOM_API_HOST)
• Check that the environment is selected 

Response: Unauthorized - No API key given

How to fix:

• If you have moved the request from the collection, put it back in the collection
  • The request relies on pre-request scripts that are stored in the collection to implement the authorization process
  • If you need to move the request, you can copy the pre-request script from the collection by clicking edit in the collection menu