Developer

v3 APIs Tips and Tricks

Manage your Tokens creation with Postman

In Postman, you can easily manage the creation and renewal of your Access Tokens. Follow these instructions:

  1. Go to Postman and create a new request
    • In the new Request, go to the Authorization tab and in Type choose Oauth 2.0
    • Take note of the Callback URL value.
  2. Now, create a new Application in Bluescape
    • Please see instructions in Application Authorization, Appendix 1
    • In the Oauth redirect ui field, use the the Postman Callback URL value.
    • Save and take note of the Client ID and Client Secret
  3. Let's go back to Postman and fill out the Oauth 2.0 Authorization utility. In Configure New Token use the following values:
    • Verify that the Authorize using browser checkbox is checked.
    • Token Name: Set name for the new Token
    • Auth URL: /authorize
    • Access Token URL: /api/v2/oauth2/token
    • Client ID: value of Bluescape Application Client ID
    • Client Secret: value of bluescape Application Client Secret
  4. The next step is to create the Access Token.
    • Scroll to the bottom of the Postman Oauth 2.0 Authorization utility
    • If available (it depends on the version of Postman you are using), click the Clear cookies button to clear the cookies.
    • Now, click the Get New Access Token button
    • A new browser window will open, you will be required to follow these steps:
      • Authenticate with Bluescape: use the same user that created the Bluescape Application. If you are already logged into Bluescape, this step will be skipped.
      • Authorize the Token Creation: click Allow.
      • Now Bluescape will redirect the process to the Callback URL for Postman, and your browser will ask you permission to pass the call to Postman, allow he link to be open.
    • A new window will open in Postman, with the brand new Access Token.
    • Click the Use Token on the top-right corner.
  5. You new Access Token is ready to be used in Postman, or you can use it in your scripts.
  6. When your Access Token expires, or you want to generate a new one, click the Get New Access Token button and follow the steps outlined above.

GraphQL introspection: query the schema

One of the most interesting features of GraphQL is introspection. Introspection is the ability to query details about the current API’s schema. You can send queries to every GraphQL API that return data about a given API’s schema. See the following example:

query GetSchema{
  __schema {
    types {
      name
      description
    }
  }
}

The query answer will be something like this:

{
    "data": {
        "__schema": {
            "types": [
                {
                    "name": "Browser",
                    "description": "web browser"
                },
                {
                    "name": "Element",
                    "description": "Basic workspace building block"
                },
                ...
        }
    }
}

You can also specify a particular type to get its details:

query ElementDetails {
  __type(name:"Element") {
    name
    fields {
      name
      description
      type {
        name
      }
    }
  }
}

And the answer is this, with the details of the specified type:

{
    "data": {
        "__type": {
            "name": "Element",
            "fields": [
                {
                    "name": "id",
                    "description": "Workspace-unique element id",
                    "type": {
                        "name": null
                    }
                },
                {
                    "name": "zIndex",
                    "description": "Stack order, an element with a higher stack order is in front of a lower stack order",
                    "type": {
                        "name": null
                    }
                },
                ...
            ]
        }
    }
}