SmartThingsNet - dotnet library for the SmartThings API

Overview

The SmartThings API supports REST, resources are protected with OAuth 2.0 Bearer Tokens, and all responses are sent as JSON.

For an example on how to use this SDK, please refer to the SmartThings Terminal cli tool.

Note: This SDK is mostly auto-generated from the public SmartThings open-api definition but with necessary compilation fixes. The underlying SmartThings API is currently in preview and has ongoing changes - so there are some discrepancies between what functionality is exposed and what is implemented. Therefore if things don't work, please check the SmartThings API behaves in the way you expect first.

Also, the documentation here is not kept up to date with the code base

Authentication

All SmartThings resources are protected with OAuth 2.0 Bearer Tokens sent on the request as an Authorization: Bearer <TOKEN> header.

Token types

Only personal access tokens are supported. These are used to interact with the API for non-SmartApp use cases. They can be created and managed on the personal access tokens page.

OAuth2 scopes

Operations may be protected by one or more OAuth security schemes, which specify the required permissions. Each scope for a given scheme is required. If multiple schemes are specified (not common), you may use either scheme.

Personal access token scopes are associated with the specific permissions authorized when creating them.

Scopes are generally in the form permission:entity-type:entity-id.

An * used for the entity-id specifies that the permission may be applied to all entities that the token type has access to, or may be replaced with a specific ID.

For more information about authrization and permissions, please see the Authorization and permissions guide.

API Versions

The SmartThings API supports both path and header-based versioning. The following are equivalent:

https://api.smartthings.com/v1/locations
https://api.smartthings.com/locations with header Accept: application/vnd.smartthings+json;v=1

Currently, only version 1 is available.

Paging

Operations that return a list of objects return a paginated response. The _links object contains the items returned, and links to the next and previous result page, if applicable.

{
  "items": [
    {
      "locationId": "6b3d1909-1e1c-43ec-adc2-5f941de4fbf9",
      "name": "Home"
    },
    {
      "locationId": "6b3d1909-1e1c-43ec-adc2-5f94d6g4fbf9",
      "name": "Work"
    }
    ....
  ],
  "_links": {
    "next": {
      "href": "https://api.smartthings.com/v1/locations?page=3"
    },
    "previous": {
      "href": "https://api.smartthings.com/v1/locations?page=1"
    }
  }
}

Localization

Some SmartThings API's support localization. Specific information regarding localization endpoints are documented in the API itself. However, the following should apply to all endpoints that support localization.

Fallback Patterns

When making a request with the Accept-Language header, this fallback pattern is observed.

Response will be translated with exact locale tag.
If a translation does not exist for the requested language and region, the translation for the language will be returned.
If a translation does not exist for the language, English (en) will be returned.
Finally, an untranslated response will be returned in the absense of the above translations.

Accept-Language Header

The format of the Accept-Language header follows what is defined in RFC 7231, section 5.3.5

Content-Language

The Content-Language header should be set on the response from the server to indicate which translation was given back to the client. The absense of the header indicates that the server did not recieve a request with the Accept-Language header set.

This C# SDK is automatically generated by the OpenAPI Generator project (then modified to work):

API version: 1.0-PREVIEW
SDK version: 1.0.0
Build package: SmartThingsNet.codegen.languages.CSharpNetCoreClientCodegen

Frameworks supported

.NET Core >=1.0
.NET Framework >=4.6
Mono/Xamarin >=vNext

Dependencies

RestSharp - 106.10.1 or later
Json.NET - 12.0.1 or later
JsonSubTypes - 1.5.2 or later
System.ComponentModel.Annotations - 4.5.0 or later

The DLLs included in the package may not be the latest version. We recommend using NuGet to obtain the latest version of the packages:

Install-Package RestSharp
Install-Package Newtonsoft.Json
Install-Package JsonSubTypes
Install-Package System.ComponentModel.Annotations

NOTE: RestSharp versions greater than 105.1.0 have a bug which causes file uploads to fail. See RestSharp#742

Installation

Generate the DLL using your preferred tool (e.g. dotnet build)

Then include the DLL (under the bin folder) in the C# project, and use the namespaces:

using SmartThingsNet.Api;
using SmartThingsNet.Client;
using SmartThingsNet.Model;

Getting Started

using System.Collections.Generic;
using System.Diagnostics;
using SmartThingsNet.Api;
using SmartThingsNet.Client;
using SmartThingsNet.Model;

namespace Example
{
    public class Example
    {
        public static void Main()
        {

            Configuration config = new Configuration();
            config.BasePath = "https://api.smartthings.com/v1";
            // Configure OAuth2 access token for authorization: Bearer
            config.AccessToken = "YOUR_ACCESS_TOKEN";

            var apiInstance = new AppsApi(config);
            var createOrUpdateAppRequest = new CreateAppRequest(); // CreateAppRequest | 
            var signatureType = signatureType_example;  // string | The Signature Type of the application. For WEBHOOK_SMART_APP only.  (optional) 
            var requireConfirmation = true;  // bool? | Override default configuration to use either PING or CONFIRMATION lifecycle. For WEBHOOK_SMART_APP only.  (optional) 

            try
            {
                // Create an app.
                CreateAppResponse result = apiInstance.CreateApp(createOrUpdateAppRequest, signatureType, requireConfirmation);
                Debug.WriteLine(result);
            }
            catch (ApiException e)
            {
                Debug.Print("Exception when calling AppsApi.CreateApp: " + e.Message );
                Debug.Print("Status Code: "+ e.ErrorCode);
                Debug.Print(e.StackTrace);
            }

        }
    }
}

Documentation for API Endpoints

All URIs are relative to https://api.smartthings.com/v1

Class	Method	HTTP request	Description
AppsApi	CreateApp	POST /apps	Create an app.
AppsApi	DeleteApp	DELETE /apps/{appNameOrId}	Delete an app.
AppsApi	GenerateAppOauth	POST /apps/{appNameOrId}/oauth/generate	Generate an app's oauth client/secret.
AppsApi	GetApp	GET /apps/{appNameOrId}	Get an app.
AppsApi	GetAppOauth	GET /apps/{appNameOrId}/oauth	Get an app's oauth settings.
AppsApi	GetAppSettings	GET /apps/{appNameOrId}/settings	Get settings.
AppsApi	ListApps	GET /apps	List apps.
AppsApi	Register	PUT /apps/{appNameOrId}/register	Sends a confirmation request to App.
AppsApi	UpdateApp	PUT /apps/{appNameOrId}	Update an app.
AppsApi	UpdateAppOauth	PUT /apps/{appNameOrId}/oauth	Update an app's oauth settings.
AppsApi	UpdateAppSettings	PUT /apps/{appNameOrId}/settings	Update settings.
AppsApi	UpdateSignatureType	PUT /apps/{appNameOrId}/signature-type	Update an app's signature type.
DeviceprofilesApi	CreateDeviceProfile	POST /deviceprofiles	Create a device profile
DeviceprofilesApi	DeleteDeviceProfile	DELETE /deviceprofiles/{deviceProfileId}	Delete a device profile
DeviceprofilesApi	GetDeviceProfile	GET /deviceprofiles/{deviceProfileId}	GET a device profile
DeviceprofilesApi	ListDeviceProfiles	GET /deviceprofiles	List all device profiles for the authenticated user
DeviceprofilesApi	UpdateDeviceProfile	PUT /deviceprofiles/{deviceProfileId}	Update a device profile.
DevicesApi	CreateDeviceEvents	POST /devices/{deviceId}/events	Create Device Events.
DevicesApi	DeleteDevice	DELETE /devices/{deviceId}	Delete a Device.
DevicesApi	ExecuteDeviceCommands	POST /devices/{deviceId}/commands	Execute commands on device.
DevicesApi	GetDevice	GET /devices/{deviceId}	Get a device's description.
DevicesApi	GetDeviceComponentStatus	GET /devices/{deviceId}/components/{componentId}/status	Get a device component's status.
DevicesApi	GetDeviceStatus	GET /devices/{deviceId}/status	Get the full status of a device.
DevicesApi	GetDeviceStatusByCapability	GET /devices/{deviceId}/components/{componentId}/capabilities/{capabilityId}/status	Get a capability's status.
DevicesApi	GetDevices	GET /devices	List devices.
DevicesApi	InstallDevice	POST /devices	Install a Device.
DevicesApi	UpdateDevice	PUT /devices/{deviceId}	Update a device.
InstalledappsApi	CreateInstalledAppEvents	POST /installedapps/{installedAppId}/events	Create Installed App events.
InstalledappsApi	DeleteInstallation	DELETE /installedapps/{installedAppId}	Delete an installed app.
InstalledappsApi	GetInstallation	GET /installedapps/{installedAppId}	Get an installed app.
InstalledappsApi	GetInstallationConfig	GET /installedapps/{installedAppId}/configs/{configurationId}	Get an installed app configuration.
InstalledappsApi	ListInstallationConfig	GET /installedapps/{installedAppId}/configs	List an installed app's configurations.
InstalledappsApi	ListInstallations	GET /installedapps	List installed apps.
LocationsApi	CreateLocation	POST /locations	Create a Location.
LocationsApi	DeleteLocation	DELETE /locations/{locationId}	Delete a Location.
LocationsApi	GetLocation	GET /locations/{locationId}	Get a Location.
LocationsApi	ListLocations	GET /locations	List Locations.
LocationsApi	UpdateLocation	PUT /locations/{locationId}	Update a Location.
RoomsApi	CreateRoom	POST /locations/{locationId}/rooms	Create a Room.
RoomsApi	DeleteRoom	DELETE /locations/{locationId}/rooms/{roomId}	Delete a Room.
RoomsApi	GetRoom	GET /locations/{locationId}/rooms/{roomId}	Get a Room.
RoomsApi	ListRooms	GET /locations/{locationId}/rooms	List Rooms.
RoomsApi	UpdateRoom	PUT /locations/{locationId}/rooms/{roomId}	Update a Room.
RulesApi	CreateRule	POST /rules	Create a rule
RulesApi	DeleteRule	DELETE /rules/{ruleId}	Delete a rule
RulesApi	ExecuteRule	POST /rules/execute/{ruleId}	Execute a rule
RulesApi	GetRule	GET /rules/{ruleId}	Get a Rule
RulesApi	ListRules	GET /rules	Rules list
RulesApi	UpdateRule	PUT /rules/{ruleId}	Update a rule
ScenesApi	ExecuteScene	POST /scenes/{sceneId}/execute	Execute Scene
ScenesApi	ListScenes	GET /scenes	List Scenes
SchedulesApi	CreateSchedule	POST /installedapps/{installedAppId}/schedules	Save an installed app schedule.
SchedulesApi	DeleteSchedule	DELETE /installedapps/{installedAppId}/schedules/{scheduleName}	Delete a schedule.
SchedulesApi	DeleteSchedules	DELETE /installedapps/{installedAppId}/schedules	Delete all of an installed app's schedules.
SchedulesApi	GetSchedule	GET /installedapps/{installedAppId}/schedules/{scheduleName}	Get an installed app's schedule.
SchedulesApi	GetSchedules	GET /installedapps/{installedAppId}/schedules	List installed app schedules.
SubscriptionsApi	DeleteAllSubscriptions	DELETE /installedapps/{installedAppId}/subscriptions	Delete all of an installed app's subscriptions.
SubscriptionsApi	DeleteSubscription	DELETE /installedapps/{installedAppId}/subscriptions/{subscriptionId}	Delete an installed app's subscription.
SubscriptionsApi	GetSubscription	GET /installedapps/{installedAppId}/subscriptions/{subscriptionId}	Get an installed app's subscription.
SubscriptionsApi	ListSubscriptions	GET /installedapps/{installedAppId}/subscriptions	List an installed app's subscriptions.
SubscriptionsApi	SaveSubscription	POST /installedapps/{installedAppId}/subscriptions	Create a subscription for an installed app.

Documentation for Models

Documentation for Authorization

Basic

Type: HTTP basic authentication

Bearer

Type: OAuth
Flow: implicit
Authorization URL: https://auth-global.api.smartthings.com
Scopes:
- r:installedapps:*: Read details about installed SmartApps, such as which devices have been configured for the installation. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
- l:installedapps: View a list of installed SmartApps. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
- w:installedapps:*: Create, update, or delete installed SmartApps. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
- r:apps:*: Read details about a SmartApp. Only applicable for personal access tokens, and the scope is limited to the SmartApps associated with the token's account.
- w:apps:*: Create, update, or delete SmartApps. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
- l:devices: View a list of devices. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
- r:devices:*: Read details about a device, including device attribute state. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token. This scope is required to create subscriptions.
- w:devices:*: Update details such as the device name, or delete a device. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
- x:devices:*: Execute commands on a device. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
- r:deviceprofiles: View details of device profiles associated with the account. Only applicable for personal access tokens.
- w:deviceprofiles: Create, update, or delete device profiles. Only applicable to personal access tokens, and the device profile must be owned by the same account associated with the token.
- i:deviceprofiles: Create devices of the type associated with the device profile. Only applicable for SmartApp tokens, and is requires the device profile and the SmartApp have the same account owner.
- r:scenes:*: Read details about a scene. For personal access tokens, the scope is limited to the account associated with the token.
- x:scenes:*: Execute a scene. For personal access tokens, the scope is limited to the account associated with the token.
- r:schedules: Read details of scheduled executions. For SmartApp tokens, the scope is restricted to the installed SmartApp. For personal access tokens, the scope is limited to the account associated with the token.
- w:schedules: Create, update, or delete schedules. For SmartApp tokens, the scope is restricted to the installed SmartApp. For personal access tokens, the scope is limited to the account associated with the token.
- l:locations: View a list of locations. Only applicable for personal access tokens, and the scope is limited to the account associated with the token.
- r:locations:*: Read details of a location, such as geocoordinates and temperature scale. For SmartApp tokens, the scope is restricted to the installed SmartApp. For personal access tokens, the scope is limited to the account associated with the token.
- w:locations:*: Create, update, and delete locations. Only applicable for personal access tokens (the scope is limited to the account associated with the token).
- r:hubs: Read hubs.
- r:security:locations:*:armstate: Read arm state in the given location.

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github/workflows		.github/workflows
docs		docs
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
GitVersion.yml		GitVersion.yml
LICENSE.txt		LICENSE.txt
README.md		README.md
SmartThingsNet.sln		SmartThingsNet.sln

License

sm0lle/SmartThingsNet

Folders and files

Latest commit

History

Repository files navigation