First released in version: 3.2 / Last updated in version: 3.9

Using the Application REST API

Overview

The Application REST API allows you to view or create objects and properties in your user data model. Once you have installed the REST API, you can view and interact with the Swagger Doc, use Bearer authentication and send requests to the API endpoints.

Authentication

From version 3.8 SP5, the SmartSpace Application REST API supports Bearer authentication. From version 3.9, the REST API requires authentication by default. The two OAuth flows that Ubisense support are Authorization Code Flow with PKCE and Client Credentials flow.

Depending on the OAuth method that you use, you need to set up either a role or scope when configuring your authentication. If you are using the PKCE flow, you need to add a role called "smartspace-rest-api-access-role". Only users that are members of this role can access the REST API. If you are using the Client Credentials flow, you need to add a scope called "smartspace-api-scope". Only applications that are added to this scope can access the REST API.

Configuring the Application REST API

Once you have configured your authentication, you will have the basic information needed to configure the settings in the REST API. On Linux, these are configured in /etc/ubisense/restapi.json. On Windows, they are in localsettings.json in the REST API installation folder; this is normally C:\Program Files (x86)\Ubisense 3\WebApiCore\Web.

The following sections are needed in the REST API settings:

• AllowHosts, to support CORS headers and allow access from external web pages

• JWTAuth, to configure the application information, and

• AuthOptions, to require authentication for all access

An example of the REST API settings is shown below. Replace the following parameters with values from your authentication configuration:

• metadataAddress: The URL where your OpenID Connect configuration is published.

• authority: The base URL of your authorization server.

• audience: The identifier for your API that clients must include in their token requests.

• nameClaim: The claim in the token that contains the username.

• validIssuers: An array of issuer URLs that are considered valid. Tokens from other issuers will be rejected.

• validateLifetime: A boolean value indicating whether the token’s lifetime should be validated.

• requireHttpsMetadata: A boolean value indicating whether HTTPS is required for the metadata endpoint.

1
2
3
4
5
6
7
8
9
"JWTAuth": {
  "metadataAddress": "https://<your-auth-server>/path/to/.well-known/openid-configuration",
  "authority": "https://<your-auth-server>",
  "audience": "<your-api-identifier>",
  "nameClaim": "preferred_username",
  "validIssuers": ["https://<your-auth-server>/path/to/issuer"],
  "validateLifetime": true,
  "requireHttpsMetadata": false
}

The parameter “validIssuers”: should be the list of valid issuers. For multi-tenant organizations, you may configure multiple valid issuers with different tenant IDs.

Once you have saved the settings, restart the REST API service, if using Linux, or the SmartSpaceCoreApi application pool, if using Windows/IIS.

Fetching the token

After configuring the REST API settings, you can fetch and use the JWT. The following code snippet shows an example of fetching and using the token for the Client Credentials flow in C#.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
internal class AuthenticationService{
    private readonly HttpClient _httpClient;
    public AuthenticationService(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }
    public async Task<string> GetAccessTokenAsync(string clientId, string clientSecret, Uri tokenEndpointUri)
    {
        var clientCredentials = new FormUrlEncodedContent(new[]
        {
        new KeyValuePair<string, string>("grant_type", "client_credentials"),
        new KeyValuePair<string, string>("client_id", clientId),
        new KeyValuePair<string, string>("client_secret", clientSecret),
    });
        var response = await _httpClient.PostAsync(tokenEndpointUri, clientCredentials);
        response.EnsureSuccessStatusCode();
        var content = await response.Content.ReadAsStringAsync();
        var tokenResponse = JsonSerializer.Deserialize<Dictionary<string, object>>(content);
        return tokenResponse["access_token"].ToString();
    }
  }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var accessToken = await _authenticationService.GetAccessTokenAsync(
    "sample-console-app",
    "<client_secret>",//Replace this with the client secret. This is a secret and should be treated as such in production scenarios
    new Uri("<token-endpoint-url>") // Replace with your token endpoint url        
  );
  _httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
  const string apiUrl = "http://localhost:5001/api/TagTypes";
  var response = await _httpClient.GetAsync(apiUrl);
  if (response.IsSuccessStatusCode)
  {
      var content = await response.Content.ReadAsStringAsync();
      Console.WriteLine("Response Content:\n" + content);
  }
  else
  {
      Console.WriteLine($"Error: {response.StatusCode}");
  }

An API specification JSON file is provided which can be used to generate your client code. The file can be found at http://localhost/smartspaceapi and clicking the link under the title.

Requests and endpoints

This section provides an overview of the requests and endpoints needed to view or create objects and properties in your user data model. Navigate to http://localhost/smartspaceapi to view the Swagger Doc and interact with the requests.

ObjectLocations

GET /api/ObjectLocations/{type}

Get the locations of all objects of the given type.

Parameters

Name	Type	Description
type (required)	string	The object type
object_names	string	A comma separated list of object names, with illegal URL characters escaped using the same schema as standard URI encoding, but with a ~ instead of a %

Responses

Code	Description
200	Success Copy Example Value [   {     "Object": "string",     "X": 0,     "Y": 0,     "Z": 0,     "Theta": 0   } ]
400	No objects with that type exist Copy Example Value {   "type": "string",   "title": "string",   "status": 0,   "detail": "string",   "instance": "string" }

PUT /api/ObjectLocations/{type}

Set the location of one or more objects of the given type.

Parameters

Name	Type	Description
type (required)	string	The object type

Request Body

A sequence of object locations to set.

Copy

Example Value

[
  {
    "Object": "string",
    "X": 0,
    "Y": 0,
    "Z": 0,
    "Theta": 0
  }
]

Responses

Code	Description
200	Success Copy Example Value [   {     "Object": "string",     "X": 0,     "Y": 0,     "Z": 0,     "Theta": 0   } ]
400	The location could not be set Copy Example Value {   "type": "string",   "title": "string",   "status": 0,   "detail": "string",   "instance": "string" }

GET /api/ObjectLocations/{type}/{name}

Get the location of an object of the given name and type.

Parameters

Name	Type	Description
name (required)	string	The object name, with illegal URL characters escaped using the same schema as standard URI encoding, but with a ~ instead of a %
type (required)	string	The object type

Responses

Code	Description
200	Success If no body is returned then no object of that type and name with a location exists Copy Example Value [   {     "Object": "string",     "X": 0,     "Y": 0,     "Z": 0,     "Theta": 0   } ]
400	The type does not exist Copy Example Value {   "type": "string",   "title": "string",   "status": 0,   "detail": "string",   "instance": "string" }

ObjectProperties

GET /api/ObjectProperties/{type}/{property}

Get a property's value for all objects of the given type. The property must be defined at this level; {type} defines the property or inherits from a type that does.

Parameters

Name	Type	Description
type (required)	string	The object type
property (required)	string	The property name
object_names	string	A comma separated list of object names, with illegal URL characters escaped using the same schema as standard URI encoding, but with a ~ instead of a %

Responses

Code	Description
200	The property values Copy Example Value [   {     "Object": "string",     "PropertyName": "string",     "PropertyValue": "string"   } ]
400	The type does not exist Copy Example Value {   "type": "string",   "title": "string",   "status": 0,   "detail": "string",   "instance": "string" }

GET /api/ObjectProperties/{type}/{name}/{property}

Get a property's value for the object of the given name and type. The property must be defined at this level; {type} defines the property or inherits from a type that does.

Parameters

Name	Type	Description
name (required)	string	The object name, with illegal URL characters escaped using the same schema as standard URI encoding, but with a ~ instead of a %
type (required)	string	The object type
property (required)	string	The property name

Responses

Code	Description
200	Success If no body is returned then no object with that name, type and property exists Copy Example Value [   {     "Object": "string",     "PropertyName": "string",     "PropertyValue": "string"   } ]
400	The type does not exist Copy Example Value {   "type": "string",   "title": "string",   "status": 0,   "detail": "string",   "instance": "string" }

PUT /api/ObjectProperties/{type}/{name}/{property}

Set a property's value for the object of the given name and type.

Note that if you set the name property of an object, the returned Object field will still use the original object name, though the return PropertyValue will be the new name.

Parameters

Name	Type	Description
name (required)	string	The object name, with illegal URL characters escaped using the same schema as standard URI encoding, but with a ~ instead of a %
type (required)	string	The object type
property (required)	string	The property name

Request Body

The property value.

Copy

Example Value

string

Responses

Code	Description
200	Success Copy Example Value {   "Object": "string",   "PropertyName": "string",   "PropertyValue": "string" }
400	The property could not be set Copy Example Value {   "type": "string",   "title": "string",   "status": 0,   "detail": "string",   "instance": "string" }

GET /api/ObjectProperties/{type}/{name}/{property}/{key}

Get all complex property values involving this object for the given property signature. Signatures can be found using the TypeProperties operations.

Parameters

Name	Type	Description
name (required)	string	The object name, with illegal URL characters escaped using the same schema as standard URI encoding, but with a ~ instead of a %
type (required)	string	The object type
property (required)	string	The property name
key (required)	integer	The position in the signature this item is located, starting at 1

Responses

Code	Description
200	Success If no body is returned then no value for this type, object and property was found Copy Example Value {   "Object": "string",   "PropertySignature": "string",   "PropertyType": "string",   "PropertyKey": 0,   "PropertyRows": [     {       "PropertyKeys": [         "string"       ],       "PropertyValue": "string"     }   ] }
400	The type does not exist, or an invalid key is used Copy Example Value {   "type": "string",   "title": "string",   "status": 0,   "detail": "string",   "instance": "string" }

PUT /api/ObjectComplexProperties/{type}/{property}/{key}

Set a complex property value.

Parameters

Name	Type	Description
type (required)	string	The object type
property (required)	string	The property name
key (required)	integer	The position in the signature this item is located, starting at 1

Request Body

The property value.

Copy

Example Value

{
  "PropertyKeys": [
    "string"
  ],
  "PropertyValue": "string"
}

Responses

Code	Description
200	Success
400	The property could not be set Copy Example Value {   "type": "string",   "title": "string",   "status": 0,   "detail": "string",   "instance": "string" }

ObjectTags

GET /api/TagTypes

Get the list of all tag types.

Parameters

There are no parameters for this request.

Responses

Code	Description
200	Returns the (possibly empty) list of tag types Copy Example Value [   "string" ]

GET /api/Tags/{tag}

Get information about a tag.

Parameters

Name	Type	Description
tag (required)	string	The tag ID

Responses

Code	Description
200	Returns information about the tag Copy Example Value {   "Tag": "string",   "Battery": "string",   "Activity": "string",   "TagType": "string",   "Object": "string" }
400	The tag ID was invalid

GET /api/ObjectTags/{type}

Get the associated tags for all objects of the given type.

Parameters

Name	Type	Description
type (required)	string	The object type
object_names	string	A comma separated list of object names, with illegal URL characters escaped using the same schema as standard URI encoding, but with a ~ instead of a %

Responses

Code	Description
200	Success Copy Example Value [   {     "Object": "string",     "Tag": "string",     "Battery": "string",     "Activity": "string",     "TagType": "string",     "TagPosition": {       "X": 0,       "Y": 0,       "Z": 0     }   } ]
400	The type does not exist

GET /api/ObjectTags/{type}/{name}

Get the associated tag for an object of the given name and type.

Parameters

Name	Type	Description
name (required)	string	The object name, with illegal URL characters escaped using the same schema as standard URI encoding, but with a ~ instead of a %
type (required)	string	The object type

Responses

Code	Description
200	Success If no body then no object of that type/name with a tag exists Copy Example Value {   "Object": "string",   "Tag": "string",   "Battery": "string",   "Activity": "string",   "TagType": "string",   "TagPosition": {     "X": 0,     "Y": 0,     "Z": 0   } }
400	The type does not exist

PUT /api/ObjectTags/{type}/{name}

Associate a tag with an object of the given name and type. This will override all pre-exisiting associations involving this tag or object. The object must already exist and the tag position "Origin" must be defined for this type.

Parameters

Name	Type	Description
name (required)	string	The object name, with illegal URL characters escaped using the same schema as standard URI encoding, but with a ~ instead of a %
type (required)	string	The object type
tag_type	string	The tag type name
position	string	The tag position in x,y,z notation

Request Body

The tag ID to associate.

Copy

Example Value

string

Responses

Code	Description
200	Association succeeded and the tag information is returned Copy Example Value {   "Object": "string",   "Tag": "string",   "Battery": "string",   "Activity": "string",   "TagType": "string",   "TagPosition": {     "X": 0,     "Y": 0,     "Z": 0   } }
400	The tag association failed

TypeHierarchy

GET /api/TypeHierarchy

Get all types with their ancestors and descendants.

Parameters

There are no parameters for this request.

Responses

Code	Description
200	Returns the list of types Copy Example Value [   {     "Type": "string",     "Ancestors": [       "string"     ],     "Descendants": [       "string"     ]   } ]

GET /api/TypeHierarchy/{type}

Get a list of ancestors and descendants for the given type.

Parameters

Name	Type	Description
type (required)	string	The object type

Responses

Code	Description
200	Returns the list of types Copy Example Value {   "Type": "string",   "Ancestors": [     "string"   ],   "Descendants": [     "string"   ] }
400	The given type is not recognized

PUT /api/TypeHierarchy

Create a new object type.

The Name of a type must be written without special characters, for example "My Type", rather than "My_Type".

Parameters

There are no parameters for this request.

Request Body

Copy

Example Value

{
    "Namespace": "string",
    "Name": "string",
    "Parents": [
        "string"
    ]
}

Responses

Code	Description
200	The type was successfully created
400	A report explaining why the type creation failed

TypeObjects

GET /api/TypeObjects/{type}

Get all objects of a given type.

Parameters

Name	Type	Description
type (required)	string	The object type
object_names	string	A comma separated list of object names

Responses

Code	Description
200	Returns the list of objects of the given type Copy Example Value [   {     "Object": "string"   } ]
400	The given type is not recognized

GET /api/TypeObjects/{type}/{name}

Get the named object of the given type. When there are multiple matching objects, the first matching object, chosen arbitrarily, is returned.

Parameters

Name	Type	Description
type (required)	string	The object type
name (required)	string	The object name

Responses

Code	Description
200	Success If no body then the object does not exist Copy Example Value [   {     "Object": "string"   } ]
400	The given type is not recognized

PUT /api/TypeObjects/{type}/{name}

Create an object of a given name and type.

Parameters

Name	Type	Description
type (required)	string	The object type
name (required)	string	The object name

Responses

Code	Description
200	The object already exists Copy Example Value {   "Object": "string" }
201	The new object was created Copy Example Value {   "Object": "string" }
400	The object could not be created (for example, the given type is not recognized)

TypeProperties

GET /api/TypeProperties/{type}

Get the list of basic properties and complex property signatures associated with the given type.

Parameters

Name	Type	Description
type (required)	string	The object type

Responses

Code	Description
200	The list of properties is returned Copy Example Value {   "Type": "string",   "Properties": [     "string"   ] }
400	The given type is not recognized

PUT /api/TypeProperties

Create a new simple property.

Required flags:

• Namespace

• Name

• OwnerType

• ValueType

If optional flags are left absent in the request body, the value defaults to false.

Note that if IsName is true then IsUnique must also be true, and IsCellular must be false. The Name of a type must be written without special characters, for example "My Type", rather than "My_Type".

Parameters

There are no parameters for this request.

Request Body

Copy

Example Value

{
    "Namespace": "string",
    "Name": "string",
    "OwnerType": "string",
    "ValueType": "string",
    "IsName": "true",
    "IsCellular": "true",
    "IsUnique": "true"
}

Responses

Code	Description
200	The property was successfully created
400	A report explaining why the property creation failed

Schemas

ObjectComplexProperty

ObjectLocation

ObjectProperty

ObjectTag

ProblemDetails

PropertyRow

TagModel

TypeHierarchy

TypeObject

TypeProperties

Vector3D