Flex Wiki Web Service

Enter a topic name to show or a new topic name to create; then press Enter

.

Summary

FlexWikiWebService is a WebService that exposes APIs for retrieving and modifying content on a FlexWiki instance.

The FlexWikiWebService is undergoing a rearchitecture to reflect changes in the internal implementation. Below are several sections: one describing the proposed architecture for the new web service, one archiving previous discussion of the existing web service architecture, one discusses and one identifies outstanding issues that need to be resolved.

In this document, "current architecture" refers to the first revision of the web service, which was in effect as of build 1615. "Proposed architecture" refers to the web service scheduled to be implemented around January 2005.

Please direct discussion of this proposed architecture to the FlexWikiUsersMailingList - this page is intended for documentation, not discussion. I will update this documentation with any consensus reached on the lists.

--CraigAndera 2004-12-23

Proposed New Architecture

Atoms

Atoms are the data structures that describe the contents of a FlexWiki instance. Web service messages are made up of combinations of one or more atoms.

Namespace

Item	Type	Description
Name	string	The name of the namespace

TopicIdentifier

A TopicIdentifier contains information to identify a particular topic.

Item	Type	Description
Namespace	string	The TopicNamespace this topic belongs to.
Name	string	The local (i.e. unqualified) name of this topic.
Version	string	The particular version of this topic. If omitted, the semantics are that the latest version is desired.

TopicInformation

TopicInformation describes the state of a particular topic.

Item	Type	Description
Identifier	TopicIdentifier	Identifies which topic

RenderedTopic

The HTML representation of a particular topic.

Item	Type	Description
Topic	TopicIdentifier	The topic this HTML is for.
HTML	string	The HTML for this topic.

TopicContents

The wiki text for a topic.

Item	Type	Description
Topic	TopicIdentifier	The topic this text is for.
Contents	string	The wiki text for this topic.

VisitorIdentity

The identity of a visitor to the wiki.

Item	Type	Description
Identity	string	Freeform text identifying the visitor.

Operations

Operations correspond to WebMethods in ASP.NET terminology. The consist of a (potentially empty) request message and an optional response message, each of which contains zero or more atoms (above).

GetAllNamespaces

Returns all the namespaces in the Federation.

Parameter	Direction	Description
Namespace[]	Out	A list of all namespaces in the federation

GetDefaultNamespace

Returns the default namespace in the Federation.

Parameter	Direction	Description
Namespace	Out	The default namespace in the Federation.

GetAllTopics

Returns all topics in a given namespace or namespaces.

Parameter	Direction	Description
Namespace[]	In	The namespaces for which to retrieve all topics.
TopicIdentifier[]	Out	The list of all topics from the requested namespaces.

GetHtml

Returns the formatted HTML for a given topic or topics.

Parameter	Direction	Description
TopicIdentifier[]	In	A list of topics for which HTML is desired
RenderedTopic[]	Out	The HTML for the requested topics.

GetText

Returns the wiki text for a given topic or topics.

Parameter	Direction	Description
TopicIdentifier[]	In	A list of topics for which to retrieve the wiki text
TopicContents[]	Out	The wiki text for the requested topics.

SetText

Sets the wiki text for a given topic.

Parameter	Direction	Description
TopicContents[]	In	A list of topics identifiers and the wiki text each should be set to. Note that the version information in the TopicIdentifier is ignored.
VisitorIdentity	In	The identity of the person making the change.

Question

Do we need an Out parameter that comes back with the new version numbers?

Opinion

I would say "Yes". DarenMay

GetVersions

Returns a collection of versions for a given topic.

Parameter	Direction	Description
TopicIdentifier[]	In	A list of topics for which version history information is requested. Note that version information is ignored.
TopicIdentifier[]	Out	A list of topics with version numbers for all previous versions for the requested topics.

GetPreview

Returns the preview HTML for a given topic.

Parameter	Direction	Description
TopicIdentifier[]	In	A list of topics for which to retrieve the preview HTML.
RenderedTopic[]	Out	The preview HTML for the requested topics.

Question

Do we want to combine this with GetHtml and provide an enumerated type that allows you to specify preview, real, or possibly others, like Print or NoWikiTalk, or whatever?

Restore

Restores a given Topic to a previous version.

Parameter	Direction	Description
TopicIdentifier[]	In	A list of previous topics and versions to restore.
VisitorIdentity	In	The identity of the visitor making the change.

GetWikiVersion

Parameter	Direction	Description
string	Out	The version of software the FlexWiki instance is using. Allows clients to gracefully degrade behavior.

Other Possible Operations

• GetLatestVersion - retrieves the latest text of a topic, or returns a "Not Modified" if the topic has not changed.
• GetDiffHtml - renders a diff between two arbitrary versions of a topic.

Versioning Strategy

Versioning is tricky. Several questions need to be answered:

• How do we maintain compatibility so that old clients can still run against a server with new software?
• Will the new functionality be implemented as additonal operations on the existing endpoint, or as a new endpoint?
• Do we need to design our data structures to allow for extension?

The "Screw It" Approach

We implement a new endpoint and disable the old one. Clients need to update to use the new definition - old tools will no longer work against new servers.

The Multiple Endpoints Approach

We implement a new endpoint, but maintain the old one. Internally, one of them can call the other one for operations that overlap.

The Single Endpoint Approach

New operations are added to the existing endpoint, and all existing operations are maintained. This is similar to the old IFoo2 COM approach.

Questions

• How do we handle error conditions on batch operations? It would be nice if there was a clean way to represent partial success. For example if one of the SetTextForTopic topics fails because it's read only, how is this reported? Should the whole operation fail? Does that mean we have to provide transactional semantics for all providers (probably infeasible)? What about providers (e.g. SQL) that do provide transactional semantics?
• There are a couple of places where we are passing in a topic but the version information is ignored even when present. Does this imply that there's another type VersionIndependentTopicInformation? TopicInformation could be an extension of that. But having more types may clutter the API more than clarify it.
• In the case where someone provides a VisitorIdentity but uses HTTP authentication mechanisms, is this parameter ignored? (That's how it works now, I believe.)
• VisitorIdentity begs the question of security in general: if we do add Forms Authentication to the web front end, we'll need an equivalent for the web service. I have some ideas of how to achieve this, but it'll need to be designed in.

Archived Discussion of Current Architecture

Methods

The FlexWikiWebService has the following methods.

public string CanEdit()

public ContentBaseCollection GetAllNamespaces()

public ContentBase GetDefaultNamespace()

public AbsoluteTopicNameCollection GetAllTopics(ContentBase cb)

public string GetHtmlForTopic(AbsoluteTopicName topicName)

public string GetHtmlForTopicVersion(AbsoluteTopicName topicName, string version)

public string GetTextForTopic(AbsoluteTopicName topicName)

public void SetTextForTopic(AbsoluteTopicName topicName, string postedTopicText, string visitorIdentityString)

public StringCollection GetVersionsForTopic(AbsoluteTopicName topicName)

public string GetPreviewForTopic(AbsoluteTopicName topicName, string textToFormat)

public void RestoreTopic(AbsoluteTopicName topicName, string visitorIdentityString, string version)

Note

Please leave comments on additional methods that are needed.

Versions

FlexWikiWebService is in Alpha right now. If you target this service before it's final, be prepared to have to refresh your proxy for the service.

History

• Reworked all the methods to return ContentBaseCollection, ContentBase, AbsoluteTopicNameCollection where necessary
• Methods now mostly take AbsoluteTopicName as parameters
• There are two GetHtmlForTopic methods, one can take a vesion as a string.
• Code is now checked in to the GDN workspace. Added a new project, Web.Service

Questions

Q Will you be able to specify the version of the topic you want in the methods above that affect topics? -- TommyWilliams

A? I would assume that you would use the canonical string representation of a topic name (which allows for an optional namespace and an optional version number). Take a look at the address bar when you're looking at a previous version of a topic and you'll see what I mean. -- DavidOrnstein

A I've revised the list of methods. As you can see, GetVersionsForTopic returns all versions for a given topic. Then you can pass in one of those version numbers into GetHtmlForTopic.

I've also added support for RestoreTopic -- OmarShahine

Comments

I wonder if this web service might be the basis for SharePointIntegration? Especially since SharePoint has a web services integration feature (which I think you need FrontPage 2003 to really play with). -- DavidOrnstein

What about overloads on the methods? If you don't specify a version or a namespace, for example, you would get the the most-recent version in the default namespace. For example:

• string GetHtmlForTopic (string topicName)
• string GetHtmlForTopic (string topicName, string nameSpace)

-- TommyWilliams

Maybe all of these methods should just use the full string representation of a topic name? That way you don't have to have all the different overloaded versions. If you have the parts you can always easily combine. If you have the fullname, you can avoid having to split it (which would be error prone). -- DavidOrnstein

What is the full Topic name version? Would it be cool for me to check in the code at this point (it's a single file). I'd like to have another set of eyes look at it becaues I am still a newbie .

BTW if you pass in null for version you get the latest version. -- OmarShahine

The full TopicName version for the previous version of this page (previous before your edit) is:

 FlexWikiWebService(2004-01-03-10-25-42.8175-davidorn@microsoft.com-12.207.223.254)

If you look at the filesystem, you'll see this is how the files are named. I see no problem with you checking in the code since it's all brand-new. Be sure to add it to the appropriate .csproj file, too -- my first check-in, I forgot. -- TommyWilliams

Here is an idea. Instead of returning and passing in strings all over the place how about I create two simple collection classes in Welcome to Fuck Wiki Forum 2_666.Web.Services namespace. They would simply wrap the existing TopicNames for a ContentBase and the ContentBases for a WikiFederation.

Doing this means I have to modify ContentBase, TopicName and Federation and put XmlIgnore so that I don't get a million exceptions trying to serialze/deserialize them.

Said classes would be:

 [Serializable]
 public class TopicNameCollection: System.Collections.CollectionBase
 {
        ...
 }


 [Serializable]
 public class TopicNameSpaceCollection: System.Collections.CollectionBase
 {
        ...
 }

Sounds reasonable. It does sounds like a change that will require some serious attention to TestingFlexWiki. -- DavidOrnstein

Just for kicks I ran all the NUnit tests. Seems if you run them all, you get failures here and there. However, if you run each test seperatley this doesn't happen. Very random, any ideas?

• Based on the code I have checked out from GDN Workspaces (Saturday, mid-day was my last grab), I don't get failures in either scenario: all tests run whether I run them all or run only selected tests. That you're seeing failures suggests that you may have made breaking code changes. You're not using a build of Whidbey, are you? -- TommyWilliams

I fonund the problem. Increasing the timeout values for Thread.Sleep to 100 miliseconds from 10 (waiting a bit more for the files to appear, fixes the problem. This probably reproes on other prople that are using a RAID-2 array. Write times are probably slower than a non RAID disk arreay.

I checked in the fix. BTW - I was runnin the tests on the latest checked out code, not mine.

I'd like to see a method to get changes since a given date

 public AbsoluteTopicNameCollection GetRecentChangedTopics(ContentBase cb, DateTime startTime)

This could be useful for a WinForm editor or a SharePoint WebPart. -- ThomasFreudenberg