Let's move along quickly to the Files web service. On the newsgroup, someone's been having problems creating files within folders in a Files tool, so this seems like good timing.
A bit of background, first, to set the stage for some of the little complexities we'll probably come across later.
The Groove Files tool is a container for binary objects (files) in a folder tree. There's a single root folder at the top of the tree, which you can't delete or rename. You can use web services methods to read the list of contents of a folder (recursively, or one level at a time), and to create, read, update and delete files and folders. Events are provided so you can subscribe for notification when files/folders are modified in the tool.
Unlike the Forms tool, which is all about structured data, the Files tool doesn't have an extensible way for you to add custom metadata to a file or folder within the tool. A file consists of a filename, some information about the creator/modifier, an ID, and maybe some file contents. So, where you need extended metadata attached to binary objects, the Files tool might not be the ideal place to store that information within a Groove workspace; you might find it more convenient to use a Forms tool with an Attachments field for the binary contents.
On the other hand, Files tools have a couple of built-in features not available with Forms attachments: binary-difference optimised change handling, and download-on-demand content.
Binary diffs are transparent to the user (and the application developer) but can make a substantial performance difference in bandwidth-constrained environments. The diff process takes each update to a file and compares it to the previous version of the file's contents; if only a small region of the file has changed, then only those bits are sent across the network to other users. (The tradeoff here is bandwidth against CPU. If the diff is not much smaller than the original file, or if calculating the difference regions takes a while, then the whole file contents are sent instead).
Download-on-demand is controllable by users, and affects web services application developers too. This feature (sometimes called "asymmetric files") separates the file stub (name, author, etc) from its contents; each member of the workspace can choose whether the actual file contents are downloaded to their machine. This is set per folder, and the user interface has a few options:
As a developer, you'll see that asymmetric files are basically enabled all the time. Every time you want to read a file's contents, you should check its download status first, otherwise you'll hit an exception.