API connection

API connection (Api / ApiSsl)

The binary MikroTik API — tik4net's default transport and the one with the full feature set: concurrent commands on one connection, streaming reads, raw sentences, Safe Mode, real in-flight cancellation. ApiSsl is the same protocol over TLS. Use these whenever the router's api or api-ssl service is on.

using tik4net;
using tik4net.Api;

var setup = new TikConnectionSetup("192.168.88.1", "admin", "");

using (ITikApiConnection connection = setup.CreateApiConnection())        // or setup.Create(TikConnectionType.Api)
{
    Console.WriteLine(connection.CreateCommand("/system/identity/print").ExecuteScalar());
}

Router prerequisites

Transport	Service	Port	Notes
Api	api	TCP 8728	enabled by default on most RouterOS installs
ApiSsl	api-ssl	TCP 8729	needs a certificate assigned to the service — see below

/ip service print where name~"api"
/ip service set api disabled=no

The user's group needs the api policy. Without it the router refuses the login with std failure: not allowed (9), which Create throws as a TikConnectionLoginRefusedException (a TikConnectionLoginException) with the router's text in RouterMessage.

What you get: ITikApiConnection

CreateApiConnection() and CreateApiSslConnection() return ITikApiConnection, the widest of the typed connection interfaces. On top of ITikConnection it has:

• CallCommandSync / CallCommandAsync — raw API sentences;
• SafeModeTake / SafeModeRelease / SafeModeUnroll — Safe Mode;
• SendTagWithSyncCommand — tagging, see below;
• AllowInvalidCertificate / CertificateValidationCallback — certificate validation.

Capabilities: every flag except the two WinBox-native ones — see the capability matrix.

Login

• RouterOS has two API login handshakes: the challenge–response of RouterOS before 6.43, and the plain login of 6.43 and newer. Api and ApiSsl handle both — tik4net tries the new form and falls back to the old one. There is nothing to configure, and there are no separate _v2 connection types.
• A login the router resets mid-handshake (RouterOS does this occasionally under load) is retried on a new socket, up to three attempts in all. The connection retries it itself, so a direct Open / OpenAsync rides it out as TikConnectionSetup.Create does.
• A wrong user or password throws TikConnectionLoginException.

Setting up API-SSL

RouterOS can only serve API-SSL with a certificate assigned: its certificate-less mode uses anonymous Diffie-Hellman cipher suites, which .NET does not support. To create a self-signed one on the router:

/certificate add name=mikrotik-CA common-name=mikrotik-CA key-usage=key-cert-sign,crl-sign
/certificate sign mikrotik-CA ca-crl-host=192.168.88.1
/certificate add name=api-ssl-server common-name=192.168.88.1
/certificate sign api-ssl-server ca=mikrotik-CA
/ip service set api-ssl disabled=no certificate=api-ssl-server

TLS 1.2 or 1.3 is negotiated by the operating system.

Certificate validation

By default the certificate is validated against the operating system's trust store, so a self-signed router certificate is rejected. Two options decide otherwise (they apply to RestSsl too):

var setup = new TikConnectionSetup(HOST, USER, PASS)
{
    AllowInvalidCertificate = true,     // accept any certificate
};

var pinned = new TikConnectionSetup(HOST, USER, PASS)
{
    // or decide yourself — pinning, a private CA; AllowInvalidCertificate is then ignored
    CertificateValidationCallback = (sender, cert, chain, errors) =>
        cert?.GetCertHashString() == expectedThumbprint,
};

using ITikApiConnection connection = setup.CreateApiSslConnection();

• Set them on the TikConnectionSetup. ConnectionFactory.OpenConnection(ApiSsl, host, user, password) has no way to pass them, so it always validates.
• An untrusted certificate throws TikConnectionSSLErrorException.

Several threads on one connection

Commands from several threads run concurrently on one API connection: each command carries a .tag word and the router's replies are routed back to the caller that sent it. SendTagWithSyncCommand is true by default, so nothing needs setting up.

((ITikTaggedConnection)connection).SendTagWithSyncCommand = false;   // only for a strictly single-threaded connection

Without the tag, concurrent commands receive each other's rows. Callback and …Async commands are always tagged. More in Threading and concurrency.

Troubleshooting

Symptom	Cause
TikConnectionProtocolMismatchException naming port 8728	ApiSsl pointed at the plain API port — use Api there
TikConnectionProtocolMismatchException naming port 8729	Api pointed at the API-SSL port — use ApiSsl
The same exception pointing at the certificate	api-ssl is on but has no certificate assigned
TikConnectionSSLErrorException	TLS was negotiated but the certificate is not trusted — see Certificate validation
TikConnectionLoginException	the router refused the login — wrong user or password
TikConnectionLoginRefusedException not allowed (9) from Create	the user's group lacks the api policy
SocketException	nothing is listening there — service disabled or filtered

An unanswered handshake ends after ConnectTimeout (15 s by default).

See also

• Connecting to a router — the setup and its options
• Low-level API — writing raw API sentences
• REST connection — the other transport with RestSsl certificate options
• WinBox CLI connection — encryption with no certificate to manage