Developing with the .NET Client

Introduction

The Web3 platform comprises a set of RESTful services that allow client applications to create, modify and delete Topic Maps and Topic Map Schemas. While all the resources and representations can be accessed and updated using HTTP operations there also exists a .NET client library that simplifies many of these tasks. This guide provides information about using the .NET client.  

Concepts

There are two sets of resources exposed by the Web3 services, resources relating to topic maps and resources relating to schemas. Examples of a resource are ‘a topic’, ‘an association’, ‘a topic map’, and ‘a schema’. While each resource can be retrieved, modified and sent back to the server on a one to one basis the client API adopts an approach that within a certain context all operations are collected into a transaction. It is this transaction that is sent to the server for execution.

The Topic Map client is an Object Orientated API over the REST service. This means that all objects are lightweight wrappers around the representation of the resource. When updates are made to the objects they in turn make updates to the underlying representations. When a commit occurs a transaction containing all affected representations is sent to the server for processing. This provides a transactional capability when updating multiple resources.

While the Web3 platform is a generic, free form, and schema free data store many of the supporting tools for editing topics and querying a topic map are driven from the schema associated with the topicmap. It is important that as part of any topicmap creation process a schema is also created and maintained. The client API provides classes to create and manage Schema instances stored by the service.

A typical development cycle is to first create a schema, then create a topic map, then synchronize the topic map with its schema. The process of synchronization does two things. Firstly it ensures that the topic map contains a topic for each of the types defined in the schema - after synchronizing the topic map with its schema you can locate these topics using the GetTopicBySubjectIdentifier method on the TopicMap object, passing in the subject identifier assigned to the type in the schema. Secondly it creates a topic map-specific version of the schema that allows schema-driven applications such as the Web3 topic map browser and topic map editor applications to retrieve the schema without having to perform synchronization. If the synchronization step is not performed or if it fails for any reason, schema-driven applications may not work as expected.

The following sections provide an overview of the client classes followed by a walk-through of common use cases. The samples described are also available as complete Visual Studio project that can be downloaded on the Web3 Platform download.