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.
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.
|X-Username||Plain text username.|
|X-Password||Plain text password.|
|X-Domain||Windows domain for Windows authentication. The header value can be empty or the header can be omitted to use the default domain.|
|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
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.
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 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
text/xml for XML serialization instead of JSON serialization but this has known issues. If the
Accept headers are missing, or they contain only unsupported content types,
application/json is used.
Do define the
Accept headers when possible. Future versions of M-Files Web Service might add more content options such as
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.