# HTTP access (mf-http-grpc)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Runtime conventions](https://developer.m-files.com/APIs/gRPC-API/index.md#runtime)

HTML version: https://developer.m-files.com/APIs/gRPC-API/runtime/http-access/

**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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/LogIn/index.md#request) 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](https://developer.m-files.com/APIs/gRPC-API/runtime/authentication/index.md).

## 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](https://developer.m-files.com/APIs/gRPC-API/runtime/call-metadata/index.md#response-metadata).

Errors are JSON:

```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](https://developer.m-files.com/APIs/gRPC-API/runtime/errors/index.md). |
| `message`, `shortMessage` | The error text. |

## Principles

* It is the same API: every rule of the runtime pages (sessions, versions, error codes, file
  transfer through download and upload sessions) applies.
* It forwards to the local endpoint of one server process. On M-Files Cloud its responses set the
  same `mfilesmsm` cookie as native gRPC responses do; keep cookies.
* Prefer native gRPC for anything that is not a browser.