The About Endpoint Tutorial

Note

This tutorial assumes you have already set up a Python environment on your machine. If not, see Setting up a Python Environment for help on how to set this up.

Definition

See the About Endpoint for a definition of this endpoint.

Tutorial

This is a very simple tutorial to get you started. After running this you should be confident that your API token and connection to the server is working.

1. Create a new empty folder

2. Create an empty text file in that folder and copy and paste the following Python code into the file and save it as a Python file (e.g. as "AboutEndpointTutorial.py"):

   """
   Requesting the versions of the libraries used by the current SolarFarmer Web API server
   """
   
   # import external libraries
   import requests   # to send the request to SF-API and get the response
   
   sf_web_api_url = 'https://solarfarmer.dnv.com/api'
   api_token = 'ENTER YOUR API TOKEN HERE!!!'
   
   # Set up the API url to call 
   about_request_url = sf_web_api_url + '/About'
   try:
       # Set up the headers for the GET API request - setting the API token and content type
       headers = {
           'Authorization': f'Bearer {api_token}',
           'ContentType': 'application/json'}
   
       # Call the HTTP GET request to the API
       response = requests.get(about_request_url, headers=headers)
   
       # Handle the response that is returned
       if (response.ok):
           json_response_text = response.json()
           print('GET Request: ' + about_request_url)
           print('Full JSON response: ' + str(json_response_text))
           print('SF-Core version: ' + json_response_text["solarFarmerCoreVersion"])
           print('SF-API version:  ' + json_response_text["solarFarmerApiVersion"])
       else:
           print(f"API request {about_request_url} failed.")
   
       # check for any status >400 and print out the reason and text as these can be useful
       if (response.status_code == 401):
           # Unauthorized - API token not valid or out of date
           print(f"Your API token is not valid for the web API url {sf_web_api_url}.")
       elif (response.status_code >= 400):
           print(f"Error status code: {response.status_code}\n" +
               f"Reason: {response.reason}\n" + f"Message: {response.text}")
   
   except Exception as exc:
       print(f"Exception thrown when calling {about_request_url}")
       print(str(exc))
   

3. Replace the text 'ENTER YOUR API TOKEN HERE!!!' with your personal API token (encase it in single quotes)

4. Open a command prompt in the folder

5. Type python AboutEndpointTutorial.py and hit Return to run the script.

6. It should return very quickly, giving some output similar to the following:

   GET Request: https://solarfarmer.dnv.com/api/About
   Full JSON response: {'solarFarmerCoreVersion': '0.2.208.0', 'solarFarmerApiVersion': '0.2.242'}
   SF-Core version: 0.2.208.0
   SF-API version:  0.2.242