Changes between Version 23 and Version 24 of S3/S3XML

Timestamp:

07/19/11 11:33:40 (13 years ago)

Author:

Dominic König

Comment:

--

S3/S3XML

@@ -59 +59 @@
 
 S3XML implements the [wiki:S3XRC/RESTfulAPI S3 RESTful API] and its [wiki:S3XRC/RESTfulAPI/URLFormat URL format] to address resources.
+
+=== RESTful Methods ===
 
 The following methods are supported:
@@ -78 +80 @@
   ||PUT <resource> ''with job ID''||commits the specified job to the database||
   ||PUT <resource> ''with source''||analyzes the source, creates an import job and commits the job to the database||
+
+=== Source Submission ===
+
+There are multiple ways to submit source files:
+
+==== Files on the Server ====
+
+A source file in the server file system can be specified using the ''filename'' URL variable:
+{{{
+PUT http://<server>/<resource>?filename=<path>
+}}}
+
+Multiple files can be specified as list of comma-separated pathnames:
+{{{
+PUT http://<server>/<resource>?filename=<path>,<path>,<path>
+}}}
+
+==== URLs ====
+
+A source file can be specified by its URL using the ''fetchurl'' URL variable:
+
+{{{
+PUT http://<server>/<resource>?fetchurl=<url>
+}}}
+
+Multiple files can be specified as list of comma-separated pathnames:
+{{{
+PUT http://<server>/<resource>?fetchurl=<url>,<url>,<url>
+}}}
+
+Supported URL protocols are http, ftp and file, where file is interpreted in the server file system context. URLs of different protocols can be mixed.
+
+The specified URLs must be accessible either without authentication, or (if you specify credentials in the URLs) they must support unsolicited HTTP basic authentication - HTTP 403 retries are not handled by the interface. The URLs must be properly [http://www.w3schools.com/tags/ref_urlencode.asp quoted], and must not contain commas.
+
+==== Request Attachments ====
+
+Source files can also be attached to a multipart-request. In this case the file extension of the source file must match the request URL file extension. Multiple files can be attached.
+
+==== Multiple Sources ====
+
+Where multiple sources are specified or attached, they are first converted and transformed one-by-one and then combined into a single element tree before import.
+
+==== Duplicate Resolution ====
+
+In the current S3 implementation, the interface does not handle duplicates within the same request. This is because the order of elements in the resulting element tree is not defined, and the last update time attribute is optional in source elements. Records must not be fractionated, but submitted in one element. Fractions of records will not be merged by the interface, and which of the fractions finally would be imported is not predictable.
+
+Source elements using unique keys are automatically matched with existing records. Where matches are ambiguous (e.g. a set of keys matching multiple existing records), the import element will be rejected as invalid. For certain resources, the server may have additional duplicate finders and resolvers configured. How duplicates are handled by these resolvers, can differ from resource to resource.
+
+The default behavior for duplicate resolution in standard import mode is to update the exiting records with the values from the source record. In synchronization mode, though, the default is to accept the newest data.
 == XML Format ==