Resource Reference Guide Overview

The Vantiq REST and WebSocket APIs provide programmatic access to the resources managed by the Vantiq server. This includes both system defined resources provided by Vantiq and custom resources created by Vantiq developers as part of their “smart systems”. In this document we will be focusing on the Vantiq system resources. For information about how to define and access custom resources or details about the resource security model, refer to the API Reference Guide.

This guide describes the structure of each resource type and the operations available on each resource type. It also describes the access privileges granted by the built-in admin and user profiles. By default admin users will have full access to all resource instances in their namespace and users will have read-only access to all resource instances in their namespace. However, there are exceptions, which are described below.

Note that all examples in this document illustrate the use of the REST API to manage the resources. Refer to the WebSockets section of the API Reference Guide for general information on managing resources using the WebSocket API.

The following resources are part of the core resource model and available for use by all Vantiq applications:

Resource Events

Some resources generate events when specific operations are performed. These events can be referenced in the WHEN statement of a rule or event stream, allowing them to trigger user defined processing whenever the event occurs. Event bindings use the “path” of the event which is always of the form: /<resource>/<resourceId>/<op> (for example /namespaces/myNamespace/authorized). The operations that trigger events and the data associated with them is described in the Events section of each resource description.

Resource Security Model

As described in the API Reference Guide all resource requests must be made by an authenticated user identity. When this identity is established the system creates a security context which includes:

Users have potential access to resource instances in two namespaces, the one to which they are bound and the system namespace. The precise details of what access is permitted for each specific resource is governed by the user’s assigned profiles. Each user has exactly 2 profiles – one which governs access to their local namespace and one which governs access to the system namespace. For each of these the system creates 2 default profiles: user and admin. The administrator of a namespace may create additional, non-default profiles for their namespace and assign these to users in that namespace as desired (bearing in mind the each user must have exactly one such profile).

In the description of each resource we will outline the access levels granted for each resource by the default user and admin profiles. The description of the Types resource includes a discussion of how to describe the default access levels for a user defined type and how to create custom access levels for use when designing custom profiles.

Default Access Levels

The default access levels that are available when defining any resource type are:

Vantiq Resources

Audits

Audits are objects created automatically by the system to track the modification of other resources in the system. A type can be defined with the “audited” flag to denote that all inserts, updates and deletes on that type should be audited. By default, operations on the following system resources will be audited:

The additional security related events will also be audited:

Audits are required to have the following properties:

Audits can optionally have the following properties:

When an audit record is created the system will assign the following additional properties to the audit record:

Access Rights

Audits cannot be updated.

Events

Events are generated for the following operations:

User Defined Audits

Operations on types defined by users will be audited if the “audited” property on the type definition is set to true.

In addition, if more fine-grained auditing is required users can define their own rules which create audits. For instance, in order to audit incoming messages from a source, you could do something like:

RULESET AuditPublishesToMySource
// Triggering condition is on any message arriving from a source named MySource
WHEN MESSAGE ARRIVES FROM MySource AS myVariable
// Construct an audit object with entity, op, ars_properties and message defined
var audit = {"entity": {resource: "sources", resourceId: "MySource"},
             "op": "publish",
             "ars_properties": { "importantProp": myVariable.importantProp },
             "message": "Message received from source MySource with value: " + myVariable.toString()}
// Manually insert the audit record
INSERT audits(audit)

This rule would create an audit record every time a message was received from the source MySource. Audits can be created from any rule or procedure, the only requirement is that the entity and message fields must be set when the audit is created.

Configurations

Configuration resources are described in detail in the Rule and Procedure Reference Guide.

Debug Configs

Debug Configurations are used to configure logging levels and turn tracing on for rules and procedures. At the time a procedure or rule is executed all of the debug configurations which refer to the rule or procedure are merged to determine the minimum logging level to allow and whether or not to enable tracing. If competing debug configurations specify different log levels for the same resource, the most verbose logging level is used. Debug configurations will be automatically generated if a logging level is set or tracing is enabled from the rule or procedure editing page in the developer portal.

Debug Configurations can be created using the standard resource API patterns:

Method: POST
URL: /api/v1/resources/debugconfigs
Body: { "name": "MyDebugConfig", 
        "type": "log",
        "value": "DEBUG",
        "resources": [
            "/rules/MyRule",
            "/procedures/MyProc",
            "/procedures/MyProc2",
            ...
        ],
        "isGlobal": false 
    }

Debug Configuration properties include:

Access Rights

Documents

A document represents a file stored in the Vantiq Database. Document instances are created by uploading the contents of the document using a multi-part MIME message of the following form:

POST https://dev.vantiq.com/api/v1/resources/documents
<your boundary marker>
Content-Disposition: form-data; name="<assignedName>"; filename="<filename>"
Content-Type: <contentType>
<file content>
<your boundary marker>

where:

In addition, the appropriate HTTP headers must be set:

ContentLength: <length of http content in aboive message>
ContentType: multipart/form-data; boundary=<your boundary marker>

Once the file has been uploaded its meta-data will be available via the resource URI - api/v1/resources/document/<assignedName>. This will return the following JSON representation:

{
    "name": "assets/img/autopsy/statement1.png"
    "fileType": "image/png",
    "content": "/docs/assets/img/autopsy/statement1.png",
}

The content property is the absolute URI that can be used to retrieve the file’s content from the Vantiq server. The fileType property is set by Vantiq based on the uploaded file’s extension, but it can be changed once the file has been uploaded (this will influence whether the file is treated as text or binary data, so care must be taken when altering this value).

Vantiq uses documents to store the system documentation available on the developer portal. Vantiq reserves the system/ document name prefix for this purpose which means that no user created documents may begin with that prefix. Within the user’s namespace the public/ prefix is used to indicate that the document contents should be available without requiring an authenticated user via the URL /ui/docs/NS/<namespace>/<relativePath> where:

For example, if you upload a document under the path public/images/myImage.png in the namespace “example”, then it will be accessible without authentication via the URI https://dev.vantiq.com/ui/docs/NS/example/images/myImage.png.

Note that the resource instance URI and the /docs URI always require authentication, even for public documents.

Access Rights

Examples

Create or Update Document

POST https://dev.vantiq.com/api/v1/resources/documents
<your boundary marker>
Content-Disposition: form-data; name="sampleDocument"; filename="sourceFile.html"
Content-Type: text/plain
This is the actual two lines of text
that is being upload as the content of the document.    
<your boundary marker>

The headers:

ContentLength: 209
ContentType: multipart/form-data; boundary=dLV9Wyq26L_-JQxk6ferf-RT153LhOO

Delete Document

DELETE https://dev.vantiq.com/api/v1/resources/documents/sampleDocument

Groups

A group is a set of users with shared access to a collection of resources. Instances of types can be defined with an ars_group field which restricts access to the record to only members of the group.

Types that are going to have group-restricted access need to be defined with the groupEnabled flag set to true on the type definition. This flag will add the extra qualifications to any query performed on the “grouped” type. The groupRequired flag can be set on the type definition as well to indicate that all inserts on the type must specify a non-null value for ars_group. Groups can be enabled without being required, in which case records with a null ars_group value will be visible to all users with access to the type.

Access Rights

Examples

Create a group

POST https://dev.vantiq.com/api/v1/resources/groups
{ "name": "myGroup",
  "owner": "myUsername",
  "members": ["myUsername", "anotherUser", "aThirdUser"]
}

Add a member to the group

PATCH https://dev.vantiq.com/api/v1/resources/groups/myGroup
{ "op": "add",
  "path": "/members/-",
  "value": "newUser"
}

Adding members can also be done via POST

POST https://dev.vantiq.com/api/v1/resources/groups/myGroup
{ "members": ["myUsername", "anotherUser", "aThirdUser", "aFourthUser"]}

The list provided via a POST will overwrite the existing list of members, so don’t forget any old users from the members list.

Remove a member from the group

PATCH https://dev.vantiq.com/api/v1/resources/groups/myGroup
    { "op": "remove",
      "path": "/members/-",
      "value": "newUser"
    }

Remove members with a POST

POST https://dev.vantiq.com/api/v1/resources/groups/myGroup
    { "members": ["myUsername", "aFourthUser"]}

This would remove “anotherUser” and “aThirdUser”.

It is not possible to remove the owner from a group, so the owner can safely be omitted from the members list without risk of dropping the owner from the group.

Logs

Logs provide access to any messages that have been logged by rules executing in the current namespace. A log message resource has the following JSON representation:

{
    "invocationId": "4de70a07-043e-43da-a407-8a9266692282",
    "level": "WARN",
    "message": "First Test",
    "sequenceId": 0,
    "timestamp": "2016-05-25T06:04:48.112Z"
}

The invocationId can be used to group messages produced by the same rule invocation. The sequenceId is used to provide an exact ordering of the messages.

Access Rights

Namespaces

Namespaces define an isolated environment for a user of the Vantiq Services. Each namespace guarantees complete separation of the data, situations, recommendations and rules from those of all other namespaces. Namespaces may optionally be associated with an organization for purposes of billing and quota management.

The namespace is established at the time the user logs in based on the users identity. Each authenticated identity is associated with one and only one namespace. To create a namespace POST the following JSON document to resource URI:

{
  "namespace": "<namespaceName>",
  "organization": {
    name: "<organizationName>",
    description: "<organizationDescription>"
  },
  "username": "<adminUsername>",
  "password": "<adminUserPassword>",
  "encryptionKey": "<encryptionKey>"
}

where

Once created the namespace resource has the following JSON representation:

{
  "namespace": "<namespaceName>",
  "organizationRef": "<organizationRef>"
}

Custom Operations

Namespaces support the following custom resource operations.

LIST AUTHORIZED USERS

Returns a list of the users who are authorized in the namespace, along with the profiles that they have been granted. The operation has no arguments.

AUTHORIZE USER

Creates a delegated request which, when executed will grant the executing user access to the namespace. The argument to this operation is a JSON document with the following properties:

REVOKE AUTHORIZATION

Revokes authorization for a user to the namespace. The argument to this command is a JSON document with the following properties:

Access Rights

Events

Events are generated for the following operations:

Examples

Create Namespace with default admin user and password

POST https://dev.vantiq.com/api/v1/resources/namespaces
{
  "namespace": "exampleNamespace"
}

Create Namespace with default admin user and password and create new organization

POST https://dev.vantiq.com/api/v1/resources/namespaces
{
  "namespace": "exampleNamespace",
  "organization": {
    "name": "MyOrganization"
    "description": "The description of my organization."
  }
}

Delete Namespace

A namespace is deleted using a DELETE REST request:

DELETE https://dev.vantiq.com/api/v1/resources/namespaces/exampleNamespace

This operation can only be performed by a namespace admin and it will remove all resource instances associated with the

Nodes

A node identifies a remote Vantiq installation that has agreed to federate with the installation in which the node is defined. A node agrees to federate with a remote node when an administrator authorized to access both the local node and the remote node, defines a node that identifies the remote installation and includes valid credentials to access the remote installation.

Register

A node is registered or updated POST on the nodes resource type. All properties in the JSON object are required including:

Example update node request:

{ 
    "op"": "updateNode",
    "object": {
        "name": "publicCloud",
        "uri": "https://api.Vantiq.com",
        "username": "myRemoteUsername",
        "password": "myRemotePassword",
        "deliveryMode: "bestEffort",
        "properties": {
            location: "CA",
            nodeType: "gateway"
        }
    }
}

Delete

A user defined node may be deleted by using the deleteNode REST request supplying the name of the node to delete. Example:

{
    "op": "deleteNode",
    "targetName": "publicCloud"
}

Access Rights

Examples

Register Node

POST https://dev.vantiq.com/api/v1/resources/nodes
{
    "name": "exampleNodeName",
    "uri": "https://api.Vantiq.com",
    "username": "myRemoteUsername",
    "password": "myRemotePassword",
    "deliveryMode: "bestEffort",
    "properties": {
        location: "CA",
        nodeType: "gateway"
    }
 }

Delete Node

DELETE https://dev.vantiq.com/api/v1/resources/nodes/exampleNodeName

Organizations

An organization represents a tenant to whom the system administrator has delegated the authority to create new namespaces. In the case of the Vantiq cloud deployment this is used to represent customers with whom Vantiq has established some form of relationship.

Organizations are created as part of creating their root namespace (see Namespace for details). They have the following properties:

Access Rights

All users except for the system admin have read-only access to the organization with which their namespace is associated (if any).

Procedures

Procedures are named operations that may be invoked from the body of a rule or used to implement the toInternal, toExternal, toConstraint and comparator actions for Scalar resources.

Procedures can also be invoked directly via the REST API by issuing a POST operation on the procedure resource instance. The body of the POST contains a JSON document describing the parameters to pass to the procedure. The result of the procedure is returned as the body of the request. Parameters may be passed by name or by position. Note that a mix of named and positional parameters are not supported. For example, the request below would invoke the procedure ConvertToCelsius with the parameter temperature set to 32.

Method: POST
URL: /api/v1/resources/procedures/ConvertToCelcius
Body: { "temperature": 32 }

Similarly, to pass the parameter positionally:

Method: POST
URL: /api/v1/resources/procedures/ConvertToCelsius
Body: [32]

Procedures are identified by their fully qualified name which is a combination of their simple name and the name of the service that they are a part of, if any. For example, the following request invokes the procedure named ConvertToCelsius which is part of the MetricConversions service.

Method: POST
URL: /api/v1/resources/procedures/MetricConversions.ConvertToCelcius
Body: { "temperature": 32 }

User defined procedures are described in the Rule and Procedure Reference Guide.

Custom Operations

Procedures support the following custom resource operations.

EXECUTE

This operation executes the procedure and returns the result. This operation accepts a single argument which can either be a JSON array or object. If an array is provided then the procedure is invoked using positional parameters where each element in the array is mapped to a procedure parameter in order. If an object is provided then the procedure is invoked using named parameters based on the property names in the supplied JSON object.

Access Rights

Profiles

A profile contains capabilities with which the user assigned the profile can access data and behaviors defined in the namespace. If a user attempts an operation that is not authorized by their assigned profile, the request will fail returning an authorization error.

Capabilities are defined in the profile properties as follows:

The profile contains the following properties:

The JSON representation of a profile:

{
  "name": "<profileName>",
  "dml": "<typeName">: 
      {
        "select": {<typeConstraint>},
        "insert": {<typeConstraint>},
        "update": {<typeConstraint>},
        "delete": {<typeConstraint>},
        "invoke": []
        }   
  "invoke": {"createType": true}
}

Default Profiles

When a namespace is created the system will automatically create 2 default profiles named user and admin. These profiles are immutable and are updated automatically as new types are defined in the namespace. The specific access level assigned in each profile is determined by the definition of the type (the default being that user will be assigned read access and admin will be assigned read/write access).

DML Capabilities

The dml property value is an object with a property for each type the user is authorized to access. The name of the property is the name of the type. The value associated with the property is an object describing the detailed capabilities assigned to the user for that type using the properties:


* update - the value is the constraint(s) on the objects that can be updated or null if all objects can be updated. For example, a user is only allowed to update financial transactions with values > $100 (‘ars_substitution_’ is defined later in this document):

  {“update”: {“total”: {“ars_substitution_gt”: “USD:100”}}}

If a type is not named in the dml property, the user had no access rights for that type.

Access Rights

Examples

Create Profile

https://dev.vantiq.com/api/v1/resources/profiles
{ "name": "myProfile",
   "dml": {myType"": {
          "select": {},
          "insert": {},
          "update": {"total" : {“pds_substitution_lt”: “USD:100”}},
          "delete": {},
          "aggregate":{},
          "invoke": []
},
"invoke": ["createType", "deleteType"]
}

Delete Profile

DELETE https://dev.vantiq.com/api/v1/resources/profile/myProfile

Rules

Rules and configurations are described in the Rule and Procedure Reference Guide

Access Rights

Scalars

Scalar resources are user defined extensions to the standard scalar types supported by Vantiq.

A scalar is defined by declaring:

The base scalar types supported by Vantiq are described in the following subsections.

Scalar Base Types

String

A String value. A maximum length may be specified.

Integer

An integer value. Integers are assumed to be signed and at least 64-bits.

Real

A double precision value. The semantics of real generally match those of a “double” in Java.

DateTime

A DateTime value. DateTime values may be presented to the system as either an ISO-compliant date time string or as a 64-bit epoch time (in milliseconds). DateTime values will always be returned from SELECT requests as ISO compliant datetime strings in the form:

yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

Please note that all times are returned normalized to UT so that there is no ambiguity when operating across multiple timezones.

Decimal

A fixed point decimal number. If a property is declared as Decimal a ‘scale’ MUST be specified. The scale is an integer that declares the number of digits of precision to carry after the decimal point.

Decimal values must be presented to the REST API as strings. SELECT always returns decimal values as Strings. The use of strings eliminates any potential rounding errors the might occur in transforming the values to/from their JSON representations.

Currency

Represents currency values (dollars, euros, etc.). The scale defaults to 4 since that appears to be a reasonable compromise for representing a wide variety of currencies. A scale other than 4 may be specified when the property is declared.

Currencies are presented to the server as strings in the form:

 “<currency code>:<value>”

where - the standard 3-digit code assigned to all currencies (eg. GBP, USD, JPY, CNY, …) value: a decimal number representing the currency value.

A property may contain values in multiple currencies but it is the user’s responsibility not to attempt nonsensical operations such as summing a property that contains values in different currencies. In such cases the user should sum the values grouping by the currency code. This is facilitated by the representation used for currency. For example, a user wishing to find sales > $100 would issue the query (in pseudo query form):

select name, sales from store where sales > “USD:100.00”

The fact that a currency MUST be specified limits the result to ONLY stores where sales are recorded in USD. If the user wishes to return all sales the query:

select name, sales from store

will return store sales for stores that report in ANY currency.

GeoJSON

A GeoJSON value representing a Point, LineString or Polygon. The value is represented as a JSON object containing two properties:

{""type"": [“Point” | “LineString” | “Polygon”], ""coordinates"": <valueSpec>}

The contains the specification of the point, line or polygon as an array of geocoordinates with each geocoordinate consisting of an array containing two or three values: the longitude and the latitude (in that order), and, optionally, the altitude in meters. Note that for a Point, the coordinates are a single array containing two (or three) values. However, for LineSegments and Polygons the coordinates are an array containing an array of geocoordinates (each nested array containing two (or three) values representing longitude and latitude (and, optionally, the altitude in meters), respectively).

Observe that the coordinate type MUST be properly capitalized and, specifically, must be one of the strings: “Point”, “LineString” or “Polygon”.

Examples:

{
  "type": "Point", 
  "coordinates": [-122.4194155, 37.7749295] 
}

{
  "type": "Polygon", 
  "coordinates": [
    [ [84.0, 40.0], [84.0, 41.0], [88.0, 41.0], [88.0, 40.0], [84.0, 40.0] ]
  ] 
}

(Point, with altitude)

{
  "type": "Point", 
  "coordinates": [-151.00708, 63.06909, 6190] 
}

ResourceReference

Represents a reference to a Vantiq resource instance. Resource references are represented in JSON as strings of the form:

/<resource>/<resourceId>

When using the REST API the above form can be used to construct a URI which references the resource instance by prepending the standard resource API prefix.

In the Vantiq data model resource references are stored as a document with the properties:

For example, given a type with a property named entity of type ResourceReference an instance of the type would appear as follow in any JSON input/output:

{
  "entity": "/myresource/2093409d29084390"
}

However, in the datastore and at runtime in any rule code the entity property would contain a document of the following form:

{
  "resource": "myresource",
  "resourceId": "2093409d29084390"
}

As a result it is possible to reference the individual sub-properties of a resource reference in a WHERE clause as follows:

SELECT * from MyType WHERE entity.resource == "myresource"

When inserting/updating a property of type ResourceReference the value can be presented in either the external “string” form or the internal “document” form. Both of these are legal:

INSERT MyType(entity: {resource: "types", resourceId: "MyType"})
INSERT MyType(entity: "/types/MyType")

Object

The Object scalar type can represent JSON objects. The object is presented to the system as a JSON-conforming object.

Access Rights

Examples

Create Scalar Type

POST https://dev.vantiq.com/api/v1/resources/scalars
{
  "name": "Length",
  "baseType": "String",
  "toInternal": "convertFeetAsStringToReal",
  "toExternal": "convertFeetAsRealToString",
  "toConstraint": "convertFeetAsStringToConstraint"
}

Delete Scalar Type

DELETE https://dev.vantiq.com/api/v1/resources/scalars/Length

Services

Services are containers for procedures which can be used both to organize a collection of related procedures into a common package and also serve to “scope” access to procedures by being part of the procedure’s resource identifier. Although services can be created directly, they will more commonly be created automatically as procedures are registered with the system (see the Rule and Procedure Reference Guide for more details).

Services have the following properties:

Access Rights

Examples

Get a Service definition

GET https://dev.vantiq.com/api/v1/resources/services/MyService
{
  "name": "MyService",
  "description": "This is a description of my service."
  "interface": ["firstProcedure", "secondProcedure"]
}

Update Service description

POST https://dev/vantiq.com/api/v1/resources/services/MyService
{
  "name": "MyService",
  "description": "This is a new description for my service."
}

Scheduled Events

Scheduled Events are events which have been scheduled for delivery at some later point in time. The schedule may specify that they be delivered once or repeatedly until deleted. Such events can be created via the resource API or by using the PUBLISH statement in VAIL.

Scheduled Events have the following properties:

Once created, one-time events can only be deleted, they may not be updated.

Access Rights

Examples

Create a one-time Scheduled Event

Here we create a one-time event that will be delivered 1 minute after our request:

POST https://dev/vantiq.com/api/v1/resources/scheduledevents
{
  "interval": 60000,
  "topic": "/myTopic",
  "message": { "value": "This is a string" }
}
{
  "name": "12345678",
  "periodic": false,
  "occursAt": "<ISO date string one minute from request time>",
  "topic": "/myTopic",
  "message": { "value": "This is a string" }
}

Here we create a one-time event that will be delivered at the specified time (which must be in the future):

POST https://dev/vantiq.com/api/v1/resources/scheduledevents
{
  "occursAt": "<ISO date string specifying a time in the future>",
  "topic": "/myTopic",
  "message": { "value": "This is a string" }
}
{
  "name": "9081399291",
  "periodic": false,
  "occursAt": "<ISO date string specifying a time in the future>",
  "topic": "/myTopic",
  "message": { "value": "This is a string" }
}

Create a periodic Scheduled Event

Here we create a scheduled event that will be delivered one hour from the request and every subsequent hour.

POST https://dev/vantiq.com/api/v1/resources/scheduledevents
{
  "name": "myEvent",
  "periodic": true,
  "occursAt": "<ISO date string specifying a time in the future>",
  "interval": 3600000,
  "topic": "/myTopic",
  "message": { "value": "This is a string" }
}
{
  "name": "myEvent",
  "periodic": true,
  "occursAt": "<ISO date string specifying a time in the future>",
  "interval": 3600000,
  "topic": "/myTopic",
  "message": { "value": "This is a string" }
}

Get a Scheduled Event definition

GET https://dev.vantiq.com/api/v1/resources/services/myEvent
{
  "name": "myEvent",
  "periodic": true,
  "occursAt": "<ISO date string specifying a time in the future>",
  "interval": 3600000,
  "topic": "/myTopic",
  "message": { "value": "This is a string" }
}

Update Scheduled Event interval

POST https://dev/vantiq.com/api/v1/resources/services/MyService
{
  "name": "myEvent",
  "interval": 60000
}

Sources

A source describes an external system that either sends data to the Vantiq server or receives data and notifications from the Vantiq server.

An overview of external system integration via sources can be found in External Source Integration Guide There are a variety of external sources predefined in Vantiq:

A source is created or updated by issuing a POST on the sources resource type. All sources must define a standard set of properties and an additional, source type specific set of configurations parameters. The JSON form of a source is as follows:

{ 
    "name": "<sourceName>",
    "type": "<sourceType>",
    "direction": "<direction>",
    "config": {
        <source type specific parameters>
    }
}

where:

A source is deleted by issuing a DELETE on the sources resource supplying the name of the source to delete.

Custom Operations

Sources support the following custom resource operations.

PUBLISH

Publishes data to the specified source. This operation accepts one argument, the data to publish. This is expected to be a JSON document.

QUERY

Performs a query operation against the specified source. This operation accepts one argument, a description of the query to perform. This is expected to be a JSON document. The details for which sources support querying and the format of their query document can be found in the documentation for each source type.

Access Rights

Examples

Create Source

Create (or update) an MQTT source:

POST https://dev.vantiq.com/api/v1/resources/sources
{ 
    "name": "myMqttSource",
    "type": "MQTT",
    "direction": "SOURCE",
    "config": {
       "serverURIs": ["tcp://me.vantiq.com:1883"],
       "topics": ["com.accessg2.stream.mqtt.example"],
       "keepAliveInterval": 30,
       "connectionTimeout": 30,
       "cleanSession": true,
    }
}

Delete Source

A user defined node may be deleted by using the deleteNode REST request supplying the name of the node to delete. Example:

DELETE https://dev.vantiq.com/api/v1/resources/sources/myMqttSource

Topics

User-defined topics for use in the Vantiq publish/subscribe model may be registered, published and deleted with the Vantiq services. Registration is optional but recommended as it enriches the metadata on which the developer portal operates.

NOTE: When specifying a topic as a resource name on the URL, the final URL always contains ‘//’ at the start of the topic name. The first ‘/’ identifies the next part of the URL and the second ‘/’ the first character of the topic name.

Custom Operations

Topics support the following custom resource operations.

Publish

A topic is published by issuing a publish request on the topic name with the body of the request containing the data associated with the publication. This data value will be delivered to any subscribed rule as the newValue property of the event.

POST https://dev.vantiq.com/api/v1/resources/topics/<topicName>
{
    <eventData>
}

Access Rights

Examples

Create Topic

POST https://dev.vantiq.com/api/v1/resources/topics
{
  "name": "/my/sample/account/update/topic",
  "description": "Published after a customer successfully updates their account info."
}

Publish Topic

POST https://dev.vantiq.com/api/v1/resources/topics//weather/denver/hourly
{
    "temp": 49,
    "wind": 2,
    "barometer": 990
}

Delete Topic

DELETE https://dev.vantiq.com/api/v1/resources/topics//weather/denver/hourly

Note that the topic name must be URL encoded in order to be placed in the DELETE URL.

Types and Series

IMPORTANT NOTE

Time Series types have been deprecated and will be replaced in a future release.

Types represent the data (objects) managed by the Vantiq System. Types are classified as either set types or series types.

A type has the following properties:

Assuming dept has the following minimal definition:

   { "name: "dept",
     "properties": {
        "name": { "type": "String" }
      },
     "naturalKey": ["name"]
   }

JSON Representation

A stylized JSON representation of a type object:

{ "name": "String",
  "properties": {"<propertyName>": {"type": "String", "required": "Boolean"},
           "<propertyName>": {"type": "String", "required": "Boolean"},
           ...
           },
  "indexes": [{"keys": [<"propertyName>", "<propertyName>", ...], "options": {"unique": "Boolean"}}]
}

Deleting Types

When a type is deleted, all instances of the type are deleted.

Compatible Type Extensions

Type definitions may be modified by authorized users. However, care must be taken if instances of the type exist at the time the type definition is modified. Vantiq recommendations that such type changes be upward compatible with existing instances fo the type:

Incompatible extensions include changing the attributes of a property. For example, if the type for a property is changed from Integer to String, the data in any existing instances of the type will not be converted to string and will generate unexpected errors when referenced. Similarly, if the multi attribute for a property is changed, the internal representation of existing instances of the type will be incorrect and will generate runtime errors.

The name, behavior and volatile attributes of a type may not be changed. The type must be re-created in order to change of these attributes.

Query Substitutions

Types support queries to identify the set of objects returned by a GET request. In order to make queries reasonably general, certain values known to the system at runtime must be available for use in queries. Such parameters may be included in a query constraint by specifying the parameter in the following form:

 {"ars_substitution": <value>}

where is a special reserved identifier.
Special reserved identifiers are available for these system-known values:

Example:

 {"name":{"ars_substitution": "ars_username" }}

Access Rights

Events

Events are generated for the following operations:

Examples

Create Type

POST https://dev.vantiq.com/api/v1/resources/types
{
  "name": "PaulType",
  "properties": {
      "empName": { "type": "String" },
      "salary": {"type": "Integer" },
      }
  "indexes": [{keys: ["empName"]]
}

Delete Type

DELETE https://dev.vantiq.com/api/v1/resources/types/PaulType

Users

A User resource defines users authorized to access Vantiq services. Each namespace supports a set of users. Users are provisioned by a namespace administrator using the POST, PUT, PATCH and DELETE REST requests.

A User resource has the following JSON representation:

{ "username": "<myUserName>",
  "password": "<myClearTextPassword>",
  "profiles": ["<profile1>", ...],
  "email": "<myEmailAddress>",
  "firstName": "<myFirstName>",
  "lastName": "<myLastName>"
}

The username property is required and must be globally unique for the Vantiq deployment. User names may contain the following characters:

This covers the most common characters used in email addresses. By convention, user names are generally defined as one of the user’s email addresses.

User names are case insensitive. Note that all other names in Vantiq are case sensitive.

The password is also required and once transmitted during the initial user creation is stored as a one-way hash value.

The profiles property is optional, but if no value is provided the system will assign the built-in user profile for both local and system access.

All other properties are optional.

Access Rights

Events

Events are generated for the following operations:

Examples

Create User

POST https://dev.vantiq.com/api/v1/resources/users
{
  "username": "paul@paulsdomain.com",
  "password": "mypassword"
}

Creates a new user named “paul@paulsdomain.com” with the password specified. In this simple example all other properties are assigned their default values.

Delete User

DELETE https://dev.vantiq.com/api/v1/resources/users/paul@paulsdomain.com

Tokens

Tokens are one of the mechanisms for authenticating requests to the Vantiq Server. Tokens can be used to create long lived secure connections between nodes in a distributed Vantiq system. In order to connect two Vantiq nodes so that one node can issue requests to the other you can use either an access token or username/ password pair.

Tokens have the following properties:

Access Rights

Examples

Create Access Token

This creates a new token with the “user” profile (from the requestors namespace) which does not expire.

Method: POST
URL: /api/v1/resources/tokens
Body: { "profiles": ["system.user"], "name": "testToken" }

Delete token or revoke access

This deletes (revokes) a previously created token

Method: DELETE
URL: /api/v1/resources/la28DUJ008LLAJllsliqo

(where la&8DUJ008LLAJllsliqo is a valid token string)