API Requests with Postman/Insomnia

Knowledge Drop

Last tested: Dec 13, 2018
 

If anyone is interested in using an API dev environment like Postman or Insomnia as an alternative to curl or the Ruby SDK there are instructions below.

What's Postman?
"Postman is the only complete API development environment, for API developers, used by more than 5 million developers and 100000 companies worldwide." (https://www.getpostman.com/)

What's Insomnia?
Similar to Postman. Allows one to organize, execute, and debug HTTP requests. Cross-platform and open source. (https://insomnia.rest/)

Steps

  1. In OAuth 2.0 set the grant type to Resource Owner Password Credentials.
  2. Enter the client_id and client_secret
  3. In advanced options select ‘in request body’ (this selects a POST login request)
  4. Select ‘Fetch Tokens’ and an access_token field will be returned in the response. Postman/Insomnia will capture that access_token value and apply it to the Authorization header in subsequent API requests. (as per OAuth 2.0 spec)
  5. Test an endpoint by adding a method (notice the GET request in the screenshot). A simple SAFE endpoint to test with that doesn't require any prior knowledge of ids is GET/api/3.1/user (aka "me()").

Looker's API login supports both POST and GET login requests.

For POST login requests, the client_id and client_secret must be passed in the body of the request, and must be x-www-form-url-encoded. The POST request must contain a Content-Type header with a value of x-www-form-url-encoded, too, or the request will fail. (Postman/Insomnia will do this for you when you select "Form URL Encoded" from the menu. For customers using low-level HTTP requests by hand, remind them to set the Content-Type because a POST without a content type is invalid HTTP and will fail before it even reaches the Looker instance.)

For GET login requests, the client_id and client_secret must be passed as URL query params. GET requests do not need a Content-Type header because GET requests don't have a request body.

POST login is strongly recommended for maximum security. Passing credentials in URL queries carries a risk that the credentials may get captured in browser histories or in a log in a server somewhere along the network route. Passing credentials in a POST body is much more secure.

Looker supports GET login requests only because some crude web tools still don't support making POST requests. This is the only justification to use GET login requests - always use POST login if possible. (and if your tools don't support POST requests, time to find better tools!)

Thanks to the OAuth 2.0 spec, Postman can figure out that GET login is possible and if you don't specify POST, Postman will default to using GET login with credentials in the URL query params. Simply select 'Fetch Tokens' and it'll figure it out. After an access token is generated you can start hitting endpoints. Below is a screenshot example of how to make the request and what it returns.

1.png

2.png

A POST login request MUST be sent as “Form URL Encoded”.

Steps

  1. Select Form URL Encoded as the body
  2. Enter client_id + client secret
  3. Post to the login endpoint

​​

​​

​​

This content is subject to limited support.                

Version history
Last update:
‎07-07-2021 01:13 PM
Updated by: