REST API Concepts and Tips


HTTP (HyperText Transfer Protocol) is a request-response protocol that is used by web applications to communicate, typically, with web servers: the client requests content from the server, the server executes that request, and the server then returns a response to the client. In a typical web browser scenario: your web browser requests a HTML file from the server (the web browser forms and sends a HTTP request), the server processes that request, and the server returns the content to the client (the server forms and sends back a HTTP response).

Visualisation of a HTTP request and response using Telerik Fiddler

A HTTP request is built of a number of parts:

A HTTP request The HTTP header (including the request line) is highlighted by a blue line, and the request body (blank in this case) highlighted by a red line.

A HTTP response is built of similar parts:

A HTTP response The HTTP header (including the response status code) is highlighted by a blue line, and the response body highlighted by a red line.

More information on HTTP can be found on Wikipedia


Unlike HTTP, REST is not a protocol. Whilst REST (Representational state transfer) is not designed to only function over HTTP, HTTP is the most common protocol over which REST functions. REST is not a language used for communication. Instead, REST is a set of architectural principles which typically include:

More information on REST can be found on Wikipedia

Serialization and Deserialization

In order to pass data structures from the calling application to the server, and back again from the server to the calling application, they must be serialised (converted to structured text) and then deserialised (converted back again). Whilst the MFWS has experimental support for data encoded in XML, most calling applications use JavaScript Object Notation instead, and this will be used in all samples.

Obtaining metadata structure element IDs

Whilst it is typically advisable to reference metadata structure elements via their aliases, alias support is not available on the M-Files Web Service. Instead, structural elements (e.g. properties, object types, classes, etc.) must be referenced by their internal ID.

Via M-Files Admin

The M-Files Admin is to administer and maintain M-Files document vaults and servers. IDs of structural elements can easily be found using this application; simply expand the vault in question, then expand the Metadata Structure (Flat View) node. By selecting each of the items within (e.g. Object Types, or Property Definitions), the item is listed alongside its ID:

Object Types

By default these lists hide built-in items. Click the Show all button to ensure that built-in items are visibile.

Value list item Ids can be viewed by selecting a value list in the section above and clicking the Contents button.

Via the M-Files Web Service

It is possible to enumerate most structural elements of an M-Files vault directly using the M-Files Web Service. The following endpoints are useful:

The /structure/objecttypes endpoint incorrectly states that it will return value lists.