Basic API Requests for v2

Developer
1
Important Notice
Bluescape is in the process of decommissioning public v2 APIs.
As part of this process, this guide will be removed from the Community at the time of the August 2023 Release. To prepare for this, visit the Basic API Requests topic to familiarize yourself with the v3 API process.

This guide assumes you have obtained an access token from an authorized user. You can obtain an access token by completing the OAuth flow see the Application Authorization.

This page contains the details for v2 REST APIs. You can also see the guide for v3 REST APIs and for v3 GraphQL APIs.

The Base URL

All API endpoints share the same base URL whether you are trying to access them through REST or GraphQL methods:

https://api.apps.us.bluescape.com

Authorization Header

All operations whether REST or GraphQL require an Authorization header based on the access tokens received from the OAuth flow. The value of this header should match the format of Bearer <access-token>.

Implementation using REST APIs

Assembling a REST Request

URL

A request URL is assembled from the base URL and the path information for an operation as found in the reference. For example, Add a User to an Organization is an operation with path /organizations/<organizationId>/users. Combining this path with the base URL gives us a request URL of:

https://api.apps.us.bluescape.com/v2/organizations/<organizationId>/users

Parameters

The path for the operation above, like many in the Bluescape API, contains a parameter. Adding a user to an organization requires we identify the organization to which the new user should be invited. To finish preparing this request URL, we must replace <organizationId> with a valid organization ID, such as one obtained from the List a User’s Organizations operation. Replacing the parameter placeholder with a sample organization ID yields a request URL of:

https://api.apps.us.bluescape.com/v2/organizations/eidzMVOsv4peKG-4DLKA/users

In addition to path parameters, some requests will have query, body and form data parameters. Reviewing the documentation for Add a User to an Organization, we see that this operation has a JSON-format body parameter, with required id, type and organizationRoleId fields. When an operation requires a body parameter, be sure to send your request with a Content-Type header of application/json. When a form data parameter is expected, be sure to send your request with a Content-Type header of multipart/form-data. A valid body for this request looks like:

{
  "id": "<SET_USER_ID>",
  "type": "<SET_MEMBER_TYPE>", #example: User
  "organizationRoleId": "<SET_ORGANIZATION_ROLE_ID>"
}

Assembled Request

Putting this all together, a request to Add a User to an Organization looks like:

cURL 
curl -X POST https://api.apps.us.bluescape.com/v2/organizations/<SET_ORGANIZATION_ID>/users \
  -H 'Authorization: Bearer <SET_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "<SET_USER_ID>",
    "type": "<SET_MEMBER_TYPE>", #example: User
    "organizationRoleId": "<SET_ORGANIZATION_ROLE_ID>"
  }'
Python 
import requests
import pprint 

portal = 'https://api.apps.us.bluescape.com'
organizationId = '<SET_ORGANIZATION_ID>';
API_version = 'v2'
API_endpoint = '/' + API_version + '/organizations/' + organizationId + '/users'
token = '<SET_TOKEN>';
data_load = {
  "id": "<SET_USER_ID>",
  "type": "<SET_MEMBER_TYPE>", #example: User
  "organizationRoleId": "<SET_ORGANIZATION_ROLE_ID>"
}

the_request = requests.post(
    portal+API_endpoint,
    headers={"Authorization": "Bearer " + token,
            "Content-Type": "application/json"
            },
    json=data_load
)

json_response = the_request.json()
pprint.pprint(json_response)

Where to Next?

Not what you were looking for? Reply below or Search the community and discover more Bluescape.