Request parameters

In addition to the resource specific parameters there are few request parameters that affect the way M-Files Web Service handles the requests with all resources.

Authentication

Almost all of the M-Files Web Service resources require either an application-level or vault-level authentication. There are three alternate ways to authenticate the requests: Two header-based approaches using either plain text credentials or encrypted authentication token or a cookie based approach using the /session and /session/vault resources.

The headers used in the header-based authentication are listed below in table 1.

Table 1: Authentication headers
Header Description
X-Username Plain text username.
X-Password Plain text password.
X-Authentication Encrypted authentication token. This can be requested through /server/authenticationtokens and /session/authenticationtoken resources.
X-Vault Document vault GUID. Application-level resources such as the document vault list can be accessed even if this header is missing.
X-ComputerName Unique identifier for the client computer. This is used mainly to distinguish check-outs from different computers. This header always overrides the computer name - even if an authentication token containing a computer name is used. The default ComputerName is M-FILES WWW for systems accessing MFWS without java enabled in their browsers. If a java enabled browser is used to access MFWS, then ComputerName will be M-FILES WWW ( NAME ), NAME being an arbritrary string to identify the machine used.

The authentication token can be created with or without the vault-information. If the token is created without the vault-information it provides only an application-level token. Application-level authentication token can be used to request the vault listing from the server in which case the listing contains vault-level authentication tokens or alternatively the application-level authentication token may be combined with the X-Vault header to acquire a vault-level authentication context.

M-Files Web Service also supports passing the header values as query parameters in case the header values cannot be modified for one reason or another. The mapping between headers and query parameters is listed in table 2 below. In case a parameter is defined both as a header and as a query parameter the header value is used.

Table 2: Authentication headers
Header Query parameter
X-Username username
X-Password password
X-Domain domain
X-Authentication auth
X-Vault vault
X-ComputerName computername

Content type negotiation

HTTP protocol defines two headers that are used to negotiate the content types used within the requests and the responses. These are the Content-Type and Accept headers. Content-Type header describes the type of content transmitted in the request or response body while the Accept header is sent by the client to the server to inform the server what kind of content the client prefers.

M-Files Web Service acknowledges this header and currently the only supported value for it is application/json save for few resource-specific exceptions. These exceptions are mainly in the resources that accept or respond with file contents. There is experimental support for application/xml or text/xml for XML serialization instead of JSON serialization but this has known issues. If the Content-Type or Accept headers are missing, or they contain only unsupported content types, application/json is used.

Do define the Content-Type and Accept headers when possible. Future versions of M-Files Web Service might add more content options such as application/html, application/xml or application/x-www-form-urlencoded. Currently passing application/html as the Accept header results in JSON serialization but if M-Files Web Service starts supporting application/html this will change and requires modifications to the application.