Package: smartdiagnostics-sdk
Release 3.22.0 with OpenApi3With our upgrade to the OpenAPI3 specification with release 3.22, a new tool was needed to handle generating our python sdk which requires some small changes to how the sdk client works which will be outlined next.Main Changes:Import modules lines have changedNew instances of each controller (resource) must be instantiated (Locations, Nodes, etc...) with client configurationThis differs from the previous version where all resource methods were available under a single client classHere is an example refactoring based on the example script below:importsmart_diagnostics_clientimportconfigparserfromsmart_diagnostics_client.restimportApiException# configurationconfiguration=configparser.ConfigParser()configuration.read("settings.ini")base_url=configuration["SDAPI"]["base_url"]bearer_token=configuration["SDAPI"]["token"]corporation_id=configuration["SDAPI"]["corporation_id"]apiConfig=smart_diagnostics_client.Configuration()apiConfig.host=base_urlbearer_header='bearer '+bearer_token# client setup with authapi_client=smart_diagnostics_client.ApiClient(apiConfig,header_name='Authorization',header_value=bearer_header)# create an instance of the API classlocation_instance=smart_diagnostics_client.LocationsApi(api_client)corporation_instance=smart_diagnostics_client.CorporationsApi(api_client)corp=corporation_instance.get_corporation(corporation_id)print("Locations for Corporation:{}".format(corp.name))try:corp_filter="CorporationId eq '{}'".format(corporation_id)location_response=location_instance.get_locations(filter=corp_filter)total_pages=location_response.total_pages# print detailsforiinrange(1,total_pages+1):location_response=location_instance.get_locations(filter=corp_filter,page=i,page_limit=10)forlocationinlocation_response.result:print(location.name)print("Id:{}".format(location.id))print("Abbreviation:{}".format(location.abbreviation))print("CorporationId:{}".format(location.corporation.corporation_id))print("Settings:{}".format(location.settings))exceptApiExceptionase:print('Exception in LocationsApi:%s'%e)Personal Access TokensStarting with release 3.13, SMARTdiagnostics provides the capability to create Personal Access Tokens (PAT) that can be used as a Bearer token to authorize API requests.  These access tokens are connected to the user that created them, acting on behalf of that SD user. Currently, the tokens are long living with no expiration date,. In the future, however, we do plan institute lifetimes to these tokens.To use the new Python SDK to access SMARTdiagnostics APIs, you must first create a Personal Access Token (PAT).  There is currently NO interface withing the SMARTdiagnostics UI to create PATs. Therefore, you will need to create one through the API after you have logged into SD in a browser. The easiest way to create tokens at this time is through our Swagger UI interface.Finally, you will only be given the actual token one time, as part of the response from the CREATE request. There is no other way to retrieve the token through other APIs. Although it is long-living, you only have one time to copy and use the token. If you lose the token, another one will have to be created.To create a PAT:Log into SDAccess theSwagger UIcontrols and look for the Users APIs near the bottom, specifically the POST toUsers/CurrentUser/tokensExpand this API and click on the "Try it Out" buttonThe POST request only requires one property, the "description" which will be shown to you in SMARTdiagnostics in the future and (currently) when you request a list of PATs through the API. Use the description to note what application this PAT is used for or why you created it.Click the blue "Execute" button and then look for the response. Thetokenproperty is your new PAT and it must be copied and saved for use later. For the purposes of this example, we will save this token to a file that will be read by the Python script.Overview of the SMARTdiagnostics Python SDKThe Python SDK provides access to all APIs exposed through the Internal APIs as well as their REQUEST and RESPONSE models. We've chosen to provide an SDK specifically for this set of Internal APIs so that we can be intentional about exposing helpful APIs that we can commit to supporting long-term. If an API is not exposed through the Internal list, then it should be considered Private, not supported outside of the KCF Development team and subject to change.There are two main advantages to using the SDK:All web request logic is handled internally. There is no need to create additional methods for handling this request/response logic.All models necessary to both make requests (POST/PUT) and to consume responses (GET) are provided. You do not have to create a set of objects/classes to hold this data.DependenciesWe currently use an application called AutoREST to create the SDK for Python. One of dependencies of the SDK that allows it to manage the requests ismsrest. This must be installed before using the SDK.pip install msrestParameter UsageIf you examine the API documentation through Swagger UI, most GET requests that allow paging take at least four standard request parameters:Filter: This is a string that specifies the properties to refine the responsePage: when a response has more than one page of items, request additional pages of data by incrementing this valuePageLimit: The number of items to include on page. Default is 10. Max is 2,000 items per page. In most cases, it will be more efficient to request the maximum so that fewer requests are made. YMMV.OrderBy: Which property to sort the response by.In general Python fashion, these request parameters are translated to their lowercase, underline separated variant which is shown in the example script (eg. "page_limit", "order_by")Settings.ini fileThe script variables, including the PAT are stored in an external file calledsettings.ini.  The format of this file matches that of theconfigparsermodule.[SDAPI]base_url=https://sd.kcftech.comtoken=0123456789+abcdefghijk/kcfcorporation_id=00000000-0000-0000-0000-000000000001Example scriptFor this simple example, we will list all of the Locations for a given Corporation. For this example, we assume that the response provides more than one page of results to show one possible way to page the results.fromsmartdiagnostics_sdkimportSmartDiagnosticsApi,modelsimportconfigparser# Get configurationconfiguration=configparser.ConfigParser()configuration.read("settings.ini")# Prod base_url example: https://sd.kcftech.combase_url=configuration["SDAPI"]["base_url"]bearer_token=configuration["SDAPI"]["token"]corporation_id=configuration["SDAPI"]["corporation_id"]# instantiate client and add token for requestssd_client=SmartDiagnosticsApi(base_url=base_url)sd_client.config.headers["Authorization"]="bearer "+bearer_token# call the locations GET APIcorporation_filter="CorporationId eq '{}'".format(corporation_id)location_response=sd_client.get_locations(filter=corporation_filter)total_pages=location_response.total_pages# Print some details for each locationprint("LOCATIONS:")foriinrange(1,total_pages+1):location_response=sd_client.get_locations(filter=corporation_filter,page=i,page_limit=10)forlocationinlocation_response.result:print(location.name)print("Id:{}".format(location.id))print("Abbreviation:{}".format(location.abbreviation))print("CorporationId:{}".format(location.corporation.corporation_id))print("Settings:{}".format(location.settings))