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 guide).
This page contains the details for REST APIs and for v3 GraphQL APIs. You can see the corresponding content for v2 REST 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>/members. Combining this path with the base URL gives us a request URL of:
https://api.apps.us.bluescape.com/v3/organizations/<organizationId>/members
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/v3/organizations/eidzMVOsv4peKG-4DLKA/members
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 example
curl -X POST https://api.apps.us.bluescape.com/v3/organizations/<SET_ORGANIZATION_ID>/members \
-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 example
import requests
import pprint
portal = 'https://api.apps.us.bluescape.com'
organizationId = '<SET_ORGANIZATION_ID>';
API_version = 'v3'
API_endpoint = '/' + API_version + '/organizations/' + organizationId + '/members'
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)
Implementation using v3 GraphQL APIs
Assembling a GraphQL Query
All GraphQL endpoints can be reached from the same URL, only the body of the request changes:
https://api.apps.us.bluescape.com/v3/graphql/
Queries can act as methods by naming them, which allows them to be reused, and even pass parameters to them in order to specify certain fields. This query is calling the /workspace/{workspaceId}/elements endpoint in order to retrieve all of the elements within that workspace, while also specifying exactly the information that should be returned. In this case the query will return the type, id, and (x,y) coordinates of all elements within the workspace. The structure of a basic GraphQL query is as follows:
query getElementsFromWorkspace($workspaceId: String!){
elements(workspaceId: $workspaceId) {
__typename
id
transform {
x y
}
}
}
These queries can be ran as-is with a tool such as Postman, or even by directly pasting them into the GraphQL Playground.
Output
{
"data": {
"elements": [
{
"__typename": "Shape",
"id": "60340962fbfaf42d19ab103f",
"transform": {
"x": -2074.9296875,
"y": -538.6084806720415
}
},
{
"__typename": "Text",
"id": "6034096bfbfaf42d19ab1042",
"transform": {
"x": -3160.056219160557,
"y": 557.3029262622199
}
},
]
}
}
Queries can be extended even further in order to drill down into the API and detail exactly what information the developer is looking for. This is really where the benefits of GraphQL start to shine. The following depicts an example where the developer only wants to retrieve information on shapes in the workspace, and additionally, only wants the id fields of those shapes:
query getElementsFromWorkspace($workspaceId: String!){
elements(workspaceId: $workspaceId, type: Shape) {
__typename
id
}
}
Output
{
"data": {
"elements": [
{
"__typename": "Shape",
"id": "60340962fbfaf42d19ab103f"
}
]
}
}
These are only the basics of what is possible with GraphQL queries. To find out more about working with them in Bluescape, continue on to the next guides page on Getting a list of Workspaces.
Where to Next?
Not what you were looking for? Reply below or Search the community and discover more Bluescape.