HTTP access (mf-http-grpc)

View as Markdown

Use native gRPC whenever your client can: services, desktop applications, scripts and coding agents. The gateway described here exists for browsers and for environments that cannot make HTTP/2 gRPC calls. It adds a hop and a process, and JSON is larger and slower to process than protobuf.

What it is

mf-http-grpc is a Node.js HTTP server that M-Files Server starts and supervises next to its gRPC endpoint. It serves the M-Files web client, and it accepts the API's calls as JSON over plain HTTP POST and forwards them to the server's local gRPC endpoint. The services, methods, messages, session model and error codes are the ones of the gRPC API.

Deployment Gateway address
On-premises http://<server>:7767 by default: the gRPC port + 1, or the registry value GRPCWEBPORT
M-Files Cloud The vault host on port 443 (HTTPS), also under the prefix /vnext

Routes

POST /grpc/v1/<kebab-method>: the method name split before each run of capitals, lowercased and joined with -. Service names are not part of the path.

Method Path
QueryVersion /grpc/v1/query-version
GetObjectTypes /grpc/v1/get-object-types
GetNamedACLs /grpc/v1/get-named-acls
DownloadFile_Begin /grpc/v1/download-file_-begin

The body is the request message as JSON. Send {} for an empty request; an empty body fails with HTTP 500. An unknown path answers HTTP 404.

Session

Log in with POST /grpc/v1/log-in and the usual LogInRequest as JSON. The reply's session_data.session_id is a base64 string (64 characters for the 48 bytes). Send it in the HTTP header M-Files-Session on later calls; the gateway turns it into the mfiles-session-id-bin metadata. KeepAlive and LogOut work as described in Authentication and sessions.

JSON encoding

Proto JSON
Field names As in the .proto (snake_case)
Enums The value's name as a string: "AUTH_DATA_TYPE_CREDENTIALS"
int64, uint64 Strings: "server_version":"7318397729964032"
bytes Base64 strings
Unset fields in replies Present with their default values (false, 0, "")

A field of the wrong kind fails with HTTP 500 and a message that names it, for example Request message serialization failure: .MFiles.ObjID.item_id: object expected.

M-Files-Response-Format: protobuf as a request header returns the reply as a binary protobuf message instead of JSON.

Responses and errors

Successful calls answer HTTP 200. Methods that return the vault's metadata structure version put it in the response header m-files-metadata-version (for example 1024); see Call metadata.

Errors are JSON:

{"message":"Not found.","shortMessage":"Not found.","statusCode":500,"errorCode":2,
 "innerExceptionCode":-2147221493}
Field Meaning
statusCode The HTTP status: 401 for an invalid session, 500 for M-Files errors.
errorCode The gRPC status code: 16 (UNAUTHENTICATED), 2 (UNKNOWN).
innerExceptionCode The M-Files error code (signed HRESULT) for UNKNOWN; see Errors.
message, shortMessage The error text.

Principles