Syntax encoding

Typed values

The value part of the typed value is encoded according to the data type. The encoding does not include the data type as this is often defined by the situation. If this is not the case the data type must be communicated together with the encoded value. Table 1 lists the different encoding schemes for different data types.

Views

View paths are encoded in the URL path based on the level hierarchy. Levels refer to views, traditional folders or virtual folders defined with typed values. The encoding format is described below in table 2. Example 1 contains encoding samples for different views.

// Root: views/items
$.get( "http://example.org/REST/views/items.aspx", callback, "json" );

// "1. Documents" view of Sample vault.
$.get( "http://example.org/REST/views/V133/items.aspx", callback, "json" );

// "1. Documents\By Customer\ESTT Corporation (IT)" of Sample vault.
$.get( "http://example.org/REST/views/V133/V136/L141/items.aspx", callback, "json" );

// "By Keyword\MFWA / MFWS" view (View ID 123)
$.get( "http://example.org/REST/views/V123/TMFWA&2520%252F%2520MFWS/items.aspx", callback, "json" );
// or
$.get( "http://example.org/REST/views/V123/TMFWA %252F MFWS/items.aspx", callback, "json" );

The double uri encoding is not strictly required in most cases. If the text value passed in the URI contains a forward slash (`/’) then the double encoding must be used. Without double encoding the forward slash will be interpreted as a view level separator.

Search conditions

Search conditions are conveyed as query parameters. The parameter starts with an expression specifier. This is followed by the operator followed by the value. The condition encoding is described in table 3. Example 2 contains some encoding samples for different searches.

* External IDs can only be used with value list searches (e.g. vl102=eABC would search for items that refer to an object of type 102 with an external ID ABC). External IDs cannot be used with property value searches (e.g. p1024=eABC would not search for items that refer to an object with an external ID ABC in property 1024).

// Quick search for "specification"
$.get( "http://example.org/REST/objects.aspx?q=specification", callback, "json" );

// Quick search for "web service"
$.get( "http://example.org/REST/objects.aspx?q=web service", callback, "json" );

// Objects where the title contains "m-files"
$.get( "http://example.org/REST/objects.aspx?p0*=m-files", callback, "json" );

// Deleted documents (Object type ID 0).
$.get( "http://example.org/REST/objects.aspx?d=true&o=0", callback, "json" );

// Quick search for "web service". Also include deleted objects.
$.get( "http://example.org/REST/objects.aspx?q=web service&d=include", callback, "json" );

// Note: Searching by external ID can be done with direct object reference.
// Customer with object ID "123A"
$.get( "http://example.org/REST/objects/136/e123A.aspx", callback, "json" );

Note that unlike M-Files API, M-Files Web Service doesn’t return deleted objects by default. Specify d=include condition to include the deleted objects as well.

External object IDs

Some endpoints can be used to interact with unmanaged objects (external objects which have not yet been promoted). However, these objects do not have internal M-Files IDs and so the typical URI format is not valid.

Instead, the ExternalRepositoryName and ExternalRepositoryObjectID from the returned ObjVer can be used instead of the “object ID” in the URI. The format of the URI element should be the letter u, followed by the ExternalRepositoryName, followed by a colon, followed by the ExternalRepositoryObjectID; the entire segment should be URL-encoded (i.e. “:” should be encoded as “%3A”). If the object contains a version then that too should be prefixed by “u” and URL-encoded.

In the samples below, the external object has an ExternalRepositoryName of e46e8488c1f94e529038e9fb80cf88b0, an ExternalRepositoryObjectID of Document!o1 and an ExternalRepositoryObjectVersionID of f46f848831f94f529038f9fb803f88b0.