REST API Quick Start Example
In this tutorial, we're going to walk through some sample code that shows you how to authenticate using the API. This example will demonstrate how you can request a token and then submit a request to obtain a list of Blueprint projects.
Request a Token
We'll start by obtaining a token by submitting an Authenticate request.
The authentication request must be sent to http://today/authentication/v1/login using the GET method. The request header must contain an Authorization header in the following format:
Authorization: Basic <EncodedCredentials>
... where <EncodedCredentials> is the Base 64 encoded string for the credentials in the following format:
<username>:<password>
If the username is jsmith and the password is Pa55w0rd, you must calculate the Base 64 encoded string for:
jsmith:Pa55w0rd
The Base 64 encoded string is anNtaXRoOlBhNTV3MHJk, and therefore the authorization header looks like this:
Authorization: Basic anNtaXRoOlBhNTV3MHJk
If your credentials are correct, the response contains the access token that you can use to submit API requests. If the Authorization header is not formatted correctly or if your credentials are incorrect, the service returns a 401 Unauthorized call error.
You can obtain the token expiry by viewing the header of the Authenticate response. The token expiry is stored in the blueprinttokenexpirydate parameter of the Authenticate response header.
Python Example
The following code demonstrates how you can obtain an access token using Python:
def get_token():
# Of course, we wouldn't normally hardcode credentials
username = "api_docs_user"
password = "Pa55w0rd"
# concatenate the username and password with : as required by rfc2617
auth_string = username + ':' + password
# encode in utf-8 and perform base64 encoding
auth_byte = auth_string.encode('utf-8')
auth_encode = base64.b64encode(auth_byte)
# decode in utf-8 string for the header
auth = auth_encode.decode('utf-8')
request_uri = 'https://production.blueprintcloud.com/authentication/v1/login'
request_header={
'Authorization' : 'Basic ' + auth,
'Accept' : 'application/json'
}
# make the request using GET
response = requests.get(request_uri, headers=request_header)
token = response.json()
return token
Submit Request
With a request token in hand, you can now submit a request (example: List Projects) to obtain data from Blueprint. You must include your access token in the Authorization header of every request.
The authorization header must look like this:
Authorization: BlueprintToken <TokenValue>
...where <TokenValue> is the token obtained from the authentication call.
Authorization: BlueprintToken 3L7b+nMqXlpE/dBptnomyZiZpZc[...Truncated...]a6cpdsCS+uWMIB5fODHItoo0fCiwP
Python Example
The following code demonstrates how you can obtain a list of Blueprint projects using Python:
def list_projects():
# obtain a token from our get_token() function
token = get_token()
# build the resource URI
resource_uri = 'https://production.blueprintcloud.com/api/v1/projects'
# build the request header
request_header={
'Authorization' : 'BlueprintToken ' + token,
'Accept' : 'application/json'
}
# specify the URI parameters
uri_parameters_list={
'Location' : 'True'
}
# create the request uri
request_uri = resource_uri + '?' + urllib.parse.urlencode(uri_parameters_list)
output_requesturi(request_uri)
# submit the request using HTTP GET method
response = requests.get(request_uri, headers=request_header)
return response
Parse the Result
After you receive a response, you will need to parse the XML or JSON data. For example, if you requested a list of projects, you will probably want to store the project data in a python list.