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.

Table 1: Typed value encoding by data type
Data type Encoding
ACL Not implemented.
Boolean ‘true’ / ‘false’
Time, Date, Timestamp ISO format string.
Floating Real number as string
Integer, Integer64 Integer as string
Lookup Integer as string. Lookup ID.
Multi-Select Lookup Comma separated Lookup-encoding.
Uninitialized Not implemented.
Text, Multi-Line Text string

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.

Table 2: ABNF of the view path encoding
viewpath = ‘/’ / level *level [ ‘/’ ]
level = ‘/’ ( view-level / folder-level / external-view-level / typed-value )
external-view-level = ‘u’ external-repository-name ‘:’ external-view-id; the repository name and view ID should be URI-encoded
view-level = ‘v’ number ; Normal view
folder-level = ‘y’ number ; Traditional folder
typed-value = data-type data-value
data-type = ‘T’ / ‘M’ ; Text, MultiLineText
/ ‘I’ / ‘J’ / ‘R’ ; Integer, Integer64, Real number
/ ‘D’ / ‘C’ / ‘E’ / ‘P’ ; Date, Time, FILETIME, Timestamp
/ ‘L’ / ‘S’ ; Lookup, MSLU
/ ‘-‘ / ‘A’ / ‘B’ ; Uninitialized, ACL, Boolean
data-value = segment-nz
; URI path segment as defined in RFC-3986. (ie.\ legal URI text, excluding `/’)
; The value is encoded according to 5.1 and then double URI encoded.
// 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" );
Example 1: View encoding examples.

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.

Table 3: ABNF of the search condition encoding
conditions condition *( ‘\&’ condition )
condition = expression operator value
expression = ‘q’ ; Quicksearch
/ ‘p’ number ; PropertyValueExpression
/ ‘vl’ number ; TypedValueExpression (Value list search)
/ ‘o’ ; Object Type
/ ‘d’ ; Is Deleted
operator = [ ‘!’ ] op-mod
op-mod = ‘=’ ; Equal
/ ‘«=’ / ‘<=’ ; Less, Less or Equal
/ ‘»=’ / ‘>=’ ; Greater, Greater or Equal
/ ‘*=’ / ‘=’ ; Matches wildcard, Contains
/ ‘\^=’ ; Starts With
value = null-value / id-value / typed-value-encoded-value / ‘include’
; See 5.1 for the typed value encoding.
; ‘include’ is a special value available for the ‘Is Deleted’ condition.
null-value = ‘\%00’ ; Equals null
id-value = number / ‘e’ string
; ‘e’ specifies external ID condition (* see note below). ID is URI escaped.

* 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" );
Example 2: Search encoding examples.

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.

Description URI
Managed object (latest version) /REST/objects/0/123/latest/properties
Unmanaged object (latest version) /REST/objects/0/ue46e8488c1f94e529038e9fb80cf88b0%3ADocument%252101/latest/properties
Managed object (specific version) /REST/objects/0/123/3/properties
Unmanaged object (specific version) /REST/objects/0/ue46e8488c1f94e529038e9fb80cf88b0%3ADocument%252101/uf46f848831f94f529038f9fb803f88b0/properties