Difference between revisions of "UBIK Web Service"

Revision as of 12:16, 22 August 2019

Standard UBIK Webservice Interface
UBIK Webservice with simplified Interface

Standard UBIK Webservice Interface

The following section describes the most important UBIK Webservice Methods used for

Fetching information about the Datamodell (Fetch MetaDefinitions)
Downloading Content objects (Download Content)
Downloading Content File Documents (Download Document)
Creating a single Content object (Create Content)
Updating Content objects (Update Contents)
Uploading a file Document (Upload Document )

Fetch MetaDefinitions

Provides the configured ACM (see Application Context Management) Datemodell to the client.

/// <summary>
/// Delivers a list of all defined MetaClass Objects for the given Application and the given DeviceID
/// </summary>
/// <param name="appName">Name of the Application</param>
/// <param name="contextName">Name of the Context</param>
/// <param name="authentication">authentication (tokenid) for the user/device to access this service</param>
/// <returns>a list of MetaDefinitions</returns>
[OperationContract]
[WebInvoke(UriTemplate = "GetMetaDefinitionsV212/{appName}/{contextName}/{authentication}/{version}", Method = "GET",
RequestFormat = WebMessageFormat.Json,
ResponseFormat = WebMessageFormat.Json)]

BCMetaDefinitions GetMetaDefinitionsV212(
String appName,
String contextName,
String authentication,
String version);

List ofParameters

Name	Type	Description
appName	String	Name of the Application
contextName	String	Name of the Context
authentication	String	Valid auth token
version	String	Indicator of the expected data format version

Code Example (c#)

string appName = "APP_TEST";
string contextName = "CTX_TEST";
string authToken = FetchValidAuthToken();
string version = "263";

UBIKContentClient target = new UBIKContentClient(WEBSERVER_NAME);

BCMetaDefinitions metaDefintions = target.GetMetaDefinitionsV212(
appName,
contextName,
authToken,
version);

Download Content

GetHierarchyDeltasV212 is used for downloading single objects as well as branches, root objects and the infrastructure.

/// <summary>
/// The main method for downloading content.
/// This method is used for downloading single objects as well as branches, root objects and the infrastructure
/// </summary>
/// <param name="appName">Name of the application.</param>
/// <param name="contextName">Name of the context.</param>
/// <param name="args">The arguments.</param>
/// <param name="authentication">authentication (tokenid) for the user/device to access this service</param>
/// <param name="version">The versionindicator.</param>
/// <returns>a set of content objects</returns>
[OperationContract]
[WebInvoke(UriTemplate = "GetMetaDefinitionsV212/{appName}/{contextName}/{authentication}/{version}", Method = "GET",
RequestFormat = WebMessageFormat.Json,
ResponseFormat = WebMessageFormat.Json)]

BCHierarchyDeltaShipments GetHierarchyDeltasV212(
String appName,
String contextName,
HierarchyDeltaArguments args,
String authentication,
String version);

List ofParameters

Name	Type	Description
appName	String	Name of the Application
contextName	String	Name of the Context
args	HierarchyDeltaArguments	Defines the type of download (root, infra, branch) as well as the startobject and the download depth
authentication	String	Valid auth token
version	String	Indicator of the expected data format version

Code Example (c#)

Downloading Root Objects

string appName = "APP_TEST";
string contextName = "CTX_TEST";
string authToken = FetchValidAuthToken();
string version = "263";

HierarchyDeltaArguments args = new HierarchyDeltaArguments()
{
ChildrenDepth = 1,
ParentDepth = 0,
StartingPoint = new HierarchyRoot(),
};

UBIKContentClient target = new UBIKContentClient(WEBSERVER_NAME);

BCHierarchyDeltaShipments roots = target.GetHierarchyDeltasV212(
appName,
contextName,
args,
authToken,
version);

Downloading Infrastructure Objects

string appName = "APP_TEST";
string contextName = "CTX_TEST";
string authToken = FetchValidAuthToken();
string version = "263";

HierarchyDeltaArguments args = new HierarchyDeltaArguments()
{
ChildrenDepth = 1,
ParentDepth = 0,
StartingPoint = new HierarchyInfrastructure(),
};

UBIKContentClient target = new UBIKContentClient(WEBSERVER_NAME);

BCHierarchyDeltaShipments roots = target.GetHierarchyDeltasV212(
appName,
contextName,
args,
authToken,
version);

Downloading an entire branch starting at object with UID = '9E8FC21E-137E-4DDB-9D85-6E71B01F12FA'

string appName = "APP_TEST";
string contextName = "CTX_TEST";
string authToken = FetchValidAuthToken();
string version = "263";

HierarchyDeltaArguments args = new HierarchyDeltaArguments()
{
ChildrenDepth = 1,
ParentDepth = 0,
StartingPoint = new HierarchyStartingPoint(new Guid("9E8FC21E-137E-4DDB-9D85-6E71B01F12FA"))
};

UBIKContentClient target = new UBIKContentClient(WEBSERVER_NAME);

BCHierarchyDeltaShipments roots = target.GetHierarchyDeltasV212(
appName,
contextName,
args,
authToken,
version);

Download a Document

Method provides a stream to the document referenced by the contentId.

/// <summary>
/// Provides a stream to the document referenced by the contentId.
/// </summary>
/// <param name="appName">Name of the application</param>
/// <param name="contextName">Name of the context</param>
/// <param name="documentId">ID of the document content object</param>
/// <param name="authentication">authentication (tokenid) for the user/device to access this service</param>
/// <param name="version">Client Web Service Version number</param>
/// <returns>A stream of the document</returns>

[OperationContract]
[WebInvoke(UriTemplate = "DownloadDocumentV212/{appName}/{contextName}/{documentId}/{authentication}/{version}", Method = "GET",
RequestFormat = WebMessageFormat.Json,
ResponseFormat = WebMessageFormat.Json)]

Stream DownloadDocumentV212(
String appName,
String contextName,
String documentId,
String authentication,
String version);

List ofParameters

Name	Type	Description
appName	String	Name of the Application
contextName	String	Name of the Context
documentId	String	ID of the document to be downloaded
authentication	String	Valid auth token
version	String	Indicator of the expected data format version

Code Example (c#)

string appName = "APP_TEST";
string ctxName = "CTX_TEST";
string authToken = FetchValidAuthToken();
string version = "263";

Guid documentId = new Guid("61ba9775-c724-40ca-b5e1-7119ab9ab553");
string filePath = "any File Path hrere";
string fileType = "*.xml";

Stream stream = null;
try
{
// ID of the object to be downloaded
Guid documentId = new Guid("61ba9775-c724-40ca-b5e1-7119ab9ab553");

UBIKContentClient target = new UBIKContentClient(WEBSERVER_NAME);

stream = target.DownloadDocumentV212(
appName,
ctxName,
documentId.ToString(),
authToken,
version);

streamReader = new StreamReader(stream);
string downloadedContent = streamReader.ReadToEnd();
}
finally
{
if (stream != null)
stream.Close();
}

Create a single Content

Method for creating a single content object and retrieving the new object as result

/// <summary>
/// Member for creating a single content object and retrieving the new object as result
/// </summary>
/// <param name="appName">The name of the application</param>
/// <param name="contextName">The name of the context the view hierarchy is defined in</param>
/// <param name="ownerID">UID of the owner object to create the new content as child</param>
/// <param name="authentication">The (valid) authentication token</param>
/// <param name="dataShipment">Data container bringing all the necessary data for creating a singe content object</param>
/// <param name="version">Client Web Service Version number</param>
/// <returns>the new content object as BCDataShipment</returns>

[OperationContract]
[WebInvoke(UriTemplate = "CreateSingleContentV212/{appName}/{contextName}/{ownerID}/{authentication}/{version}", Method = "POST",
RequestFormat = WebMessageFormat.Json,
BodyStyle = WebMessageBodyStyle.Bare,
ResponseFormat = WebMessageFormat.Json)]

BCDataShipment CreateSingleContentV212(
String appName,
String contextName,
String ownerID,
String authentication,
UbikContent dataShipment,
String version);

List ofParameters

Name	Type	Description
appName	String	Name of the Application
contextName	String	Name of the Context
ownerID	String	ID of the owner object the new content is related to (as a child)
authentication	String	Valid auth token
dataShipment	UbikContent	Content of the new object (MetaInformation and Property - Values)
version	String	Indicator of the expected data format version

Code Example (c#)

string appName = "APP_TEST";
string ctxName = "CTX_TEST";
string authToken = FetchValidAuthToken();
string version = "263";

// ID of the owner object the new content is related to (as a child)
string ownerID = new Guid("533f1ca1-0ee0-424f-a115-0a09bbfaa6de").ToString();

UbikContent newContent = new UbikContent()
{
// reference to the MetaDefinition
MetaClassID = new Guid("6b4bd904-8504-4e05-93dd-ae120d15a5be"),
// new Object => create a new UID
UID = Guid.NewGuid()
};

newContent.PropertyValues = new UBIK.Service.PropertyValue[]
{
new TypePropertyValue<string>()
{
// value to set
Value = "TESTVALUE",
// reference to the MetaProperty definition
MetaPropertyID = new Guid("4ec5281a-e0bd-4917-aff5-708352fc6953")},

new TypePropertyValue<int?>()
{
// value to set
Value = int.MaxValue,
// reference to the MetaProperty definition
MetaPropertyID = new Guid("7c95ec83-a399-4b47-b827-6d87795a7b19")},
};

UBIKContentClient target = new UBIKContentClient(WEBSERVER_NAME);

BCDataShipment result = target.CreateSingleContentV212(
appName,
ctxName,
ownerID,
authToken,
newContent,
version);

Update Contents

Method for updating a set of content objects and retrieving the updated objects as result

/// <summary>
/// Member for updating a set of content objects and retrieving the updated objects as result
/// </summary>
/// <param name="appName">The name of the application</param>
/// <param name="contextName">The name of the context the view hierarchy is defined in</param>
/// <param name="authentication">The (valid) authentication token</param>
/// <param name="dataShipment">Data container bringing all the necessary data for updating a set of content objects</param>
/// <param name="version">Client Web Service Version number</param>
/// <returns>a set of updated content objects as BCDataShipments</returns>

[OperationContract]
[WebInvoke(UriTemplate = "UpdateContentListV212/{appName}/{contextName}/{authentication}/{version}", Method = "POST",
RequestFormat = WebMessageFormat.Json,
BodyStyle = WebMessageBodyStyle.Bare,
ResponseFormat = WebMessageFormat.Json)]

BCDataShipments UpdateContentListV212(string appName, string contextName, string authentication, UbikContent[] dataShipments, string version);

List ofParameters

Name	Type	Description
appName	String	Name of the Application
contextName	String	Name of the Context
authentication	String	Valid auth token
dataShipments	UbikContent[]	Content objects to be updated (MetaInformation and Property - Values)
version	String	Indicator of the expected data format version

Code Example (c#)

string appName = "APP_TEST";
string ctxName = "CTX_TEST";
string authToken = FetchValidAuthToken();
string version = "263";

UbikContent updateContent = new UbikContent()
{
// reference to the MetaDefinition
MetaClassID = new Guid("6b4bd904-8504-4e05-93dd-ae120d15a5be"),
// update object => we must use the UID of an existing content object
UID = new Guid("6b4bd904-8504-4e05-93dd-ae120d15a5be")
};

updateContent.PropertyValues = new UBIK.Service.PropertyValue[]
{
new TypePropertyValue<string>()
{
// value to update
Value = "TESTVALUE",
// reference to the MetaProperty definition
MetaPropertyID = new Guid("4ec5281a-e0bd-4917-aff5-708352fc6953")},

new TypePropertyValue<int?>()
{
// value to update
Value = int.MaxValue,
// reference to the MetaProperty definition
MetaPropertyID = new Guid("7c95ec83-a399-4b47-b827-6d87795a7b19")},
};

UBIKContentClient target = new UBIKContentClient(WEBSERVER_NAME);

BCDataShipment result = target.UpdateContentListV212(
appName,
ctxName,
authToken,
new UbikContent[] { updateContent },
version);

Upload Document

Method for updating a set of content objects and retrieving the updated objects as result

/// <summary>
/// Uploads a file to the Server.
/// </summary>
/// <param name="stream">The stream of the file.</param>
/// <returns>The Content objet of the uploaded file</returns>

[OperationContract]
[WebInvoke(UriTemplate = "UploadFile", Method = "POST",
ResponseFormat = WebMessageFormat.Json)]

BCDataShipment UploadFile(Stream stream);

List of Parameters

Name	Type	Description
appName	String	Name of the Application (must be specified in the header)
contextName	String	Name of the Context (must be specified in the header)
authentication	String	Valid auth token (must be specified in the header)
fileTypeValue	String	FileType of the uploaded file (must be specified in the header)
documentId	String	UID of the related Content Instance (must be specified in the header)
version	String	Indicator of the expected data format version (must be specified in the header)

Code Example (c#)

string appName = "APP_TEST";
string ctxName = "CTX_TEST";
string authToken = FetchValidAuthToken();
string version = "263";

Guid documentId = new Guid("61ba9775-c724-40ca-b5e1-7119ab9ab553");
string filePath = "any File Path hrere";
string fileType = "*.xml";

Stream stream = null;
try
{
stream = new FileStream(filePath, FileMode.Open);
using (OperationContextScope scope = new OperationContextScope(target.InnerChannel))
{
HttpRequestMessageProperty headerProperty = new HttpRequestMessageProperty();
headerProperty.Headers.Add("appName", appName);
headerProperty.Headers.Add("contextName", ctxName);
headerProperty.Headers.Add("authentication", authToken);
headerProperty.Headers.Add("documentId", documentId.ToString());
headerProperty.Headers.Add("fileType", fileType);

OperationContext.Current.OutgoingMessageProperties.Add(HttpRequestMessageProperty.Name, headerProperty);

UBIKContentClient target = new UBIKContentClient(WEBSERVER_NAME);
BCDataShipment result = target.UploadFile(stream);
}
}
finally
{
if (stream != null)
stream.Close();
}

UBIK Webservice with simplified Interface

Create Content

WebCreateContent provides the possibility to create a single content object.

/// <summary>
/// WebCreateContent provides the possibility to create a single content object.
/// WebCreateContent provides a simplified interface optimized for being used in simple use cases (IOT).
/// </summary>
/// <param name="app">The application.</param>
/// <param name="context">The context.</param>
/// <param name="metaClassUID">ID of the MetaClass (Type) of the new instance.</param>
/// <param name="parentUID">ID of the hierarchical parent of the new instance.</param>
/// <param name="authentication">Authentication (tokenid) for the user/device to access this service</param>
/// <param name="version">Client Web Service Version number.</param>
/// <returns>The ID of the new instance if creation was successfull, Guid.Empty otherwise. </returns>
[OperationContract]
[WebInvoke(UriTemplate = "WebCreateContent/{app}/{context}/{metaClassUID}/{parentUID}/{authentication}/{version}", Method = "GET",
RequestFormat = WebMessageFormat.Json,
ResponseFormat = WebMessageFormat.Json)]
Guid WebCreateContent(string app, string context, string metaClassUID, string parentUID, string authentication, string version);

List ofParameters

Name	Type	Description
app	String	Name of the Application
context	String	Name of the Context
metaClassUID	String/Guid	ID of the MetaClass (Type) of the new instance.
parentUID	String/Guid	ID of the hierarchical parent of the new instance.
authentication	String	Valid auth token
version	String	Indicator of the expected data format version

@@ Line 1: / Line 1: @@
-= BLA BLA BLA =
+= Standard UBIK Webservice Interface =
 The following section describes the most important UBIK Webservice Methods used for
 * Fetching information about the Datamodell (Fetch MetaDefinitions)
@@ Line 559: / Line 559: @@
 	}
 </source>
+= UBIK Webservice with simplified Interface =
+== Create Content ==
+WebCreateContent provides the possibility to create a single content object.
+<source lang="csharp">
+        /// <summary>
+        /// WebCreateContent provides the possibility to create a single content object.
+        /// WebCreateContent provides a simplified interface optimized for being used in simple use cases (IOT).
+        /// </summary>
+        /// <param name="app">The application.</param>
+        /// <param name="context">The context.</param>
+        /// <param name="metaClassUID">ID of the MetaClass (Type) of the new instance.</param>
+        /// <param name="parentUID">ID of the hierarchical parent of the new instance.</param>
+        /// <param name="authentication">Authentication (tokenid) for the user/device to access this service</param>
+        /// <param name="version">Client Web Service Version number.</param>
+        /// <returns>The ID of the new instance if creation was successfull, Guid.Empty otherwise. </returns>
+        [OperationContract]
+        [WebInvoke(UriTemplate = "WebCreateContent/{app}/{context}/{metaClassUID}/{parentUID}/{authentication}/{version}", Method = "GET",
+                   RequestFormat = WebMessageFormat.Json,
+                   ResponseFormat = WebMessageFormat.Json)]
+        Guid WebCreateContent(string app, string context, string metaClassUID, string parentUID, string authentication, string version);
+</source>
+=== List ofParameters ===
+{| class="wikitable" | width = "50%"
+|-
+! Name!! Type !! Description
+|-
+| app|| String || Name of the Application
+|-
+| context|| String || Name of the Context
+|-
+| metaClassUID|| String/Guid || ID of the MetaClass (Type) of the new instance.
+|-
+| parentUID|| String/Guid || ID of the hierarchical parent of the new instance.
+|-
+| authentication|| String || Valid auth token
+|-
+| version|| String || Indicator of the expected data format version
+|-
+|}
 <headertabs />
 [[Category:Server|Web Service]]