API

Application Programming Interface (API) stelt gebruikers in staat om eigen softwareoplossingen te maken die met RouterOS communiceren voor het verzamelen van informatie, het aanpassen van de configuratie en het beheren van de router. De API volgt de syntaxis van de command-line interface (CLI) nauwgezet. U kunt deze gebruiken om vertaalde of aangepaste configuratietools te maken die het bedienen en beheren van RouterOS-routers eenvoudiger maken.

De API-dienst moet zijn ingeschakeld voordat u probeert een verbinding tot stand te brengen. Standaard gebruikt de API de TCP-poorten 8728 en 8729 (beveiligd).

De API-SSL-dienst kan in twee modi werken: met of zonder certificaat. Zonder een certificaat in de instellingen van /ip service moet de client een anonieme Diffie-Hellman-cipher gebruiken om een verbinding tot stand te brengen. Als de dienst een certificaat gebruikt, kan de client een TLS-sessie opzetten.

Protocol

Je communiceert met de router door sentences te versturen en één of meer sentences terug te ontvangen. Een sentence is een reeks words die wordt afgesloten door een word met lengte nul. Een word is een deel van een sentence dat op een bepaalde manier is gecodeerd: de gecodeerde lengte gevolgd door data. Wanneer de router een volledige sentence ontvangt (command word, één of meer attribute words en een word met lengte nul), evalueert en voert hij de sentence uit en stelt daarna een antwoord samen dat wordt teruggestuurd.

API-sentences

Sentence is het belangrijkste object voor communicatie met de API.

• Lege sentences worden genegeerd.
• Een sentence wordt verwerkt nadat een woord met lengte nul is ontvangen.
• Er geldt een limiet voor het aantal en de grootte van zinnen die de client kan verzenden voordat deze is ingelogd.
• Vertrouw niet op de volgorde van de attribuutwoorden, want de volgorde en het aantal kunnen door het attribuut .proplist worden gewijzigd.

De structuur van de zin is als volgt:

• Het eerste woord moet een command word bevatten.
• De zin moet een woord met lengte nul bevatten om de zin af te sluiten.
• De zin kan nul of meer attribuutwoorden bevatten. De volgorde van attribuutwoorden maakt niet uit.
• De zin kan nul of meer querywoorden bevatten. De volgorde van querywoorden is belangrijk.

Gevaar Als er geen woord met lengte nul wordt aangeleverd, begint de router de verzonden woorden niet te verwerken en beschouwt hij alle volgende invoer als onderdeel van dezelfde zin.

API-woorden

• Woorden worden gegroepeerd in zinnen. Een woord met lengte nul beëindigt een zin.
• Elk woord wordt gecodeerd als een lengte gevolgd door dat aantal bytes aan inhoud.
• Het schema maakt het coderen van lengtes tot 0xFFFFFFFF mogelijk; alleen lengtes van vier bytes worden ondersteund.
• len bytes worden verzonden met de meest significante byte eerst (netwerkvolgorde).
• Als de eerste byte van het woord >= 0xF8 is, is het een gereserveerde controlebyte. Na het ontvangen van een onbekende controlebyte kan een API-client niet verder omdat deze niet weet hoe de volgende bytes moeten worden geïnterpreteerd.
• Momenteel worden de controlebytes niet gebruikt.

De lengte van het woord wordt als volgt gecodeerd:

Over het algemeen kunnen words als volgt worden beschreven: <encoded-word-length><word-content>. De woordinhoud kan worden onderverdeeld in vijf delen: command word, attribute word, API attribute word, query word en reply word

Commandowoord

Het eerste woord in de zin moet een commando zijn, gevolgd door attribuutwoorden en een woord met lengte nul of een afsluitend woord. De naam van het commandowoord moet beginnen met een schuine streep (/). Namen van commando's volgen de CLI nauwgezet. Spaties tussen padobjecten worden niet ondersteund; ze moeten vervangen worden door schuine strepen (/).

Sommige commando's zijn specifiek voor de API:

• login - gebruikt voor het inlogproces om inloggegevens te verstrekken.
• cancel - gebruikt om het momenteel lopende commando te annuleren.

Structuur van het commandowoord in strikte volgorde:

• gecodeerde lengte
• content-prefix /
• Omgezet CLI-commando

Enkele voorbeelden van de inhoud van commandowoorden:

/login

/user/active/listen

/interface/vlan/remove

/system/reboot

Attribuutwoord

Elk command word heeft zijn eigen lijst met attribute words, afhankelijk van de inhoud.

De structuur van het attribute word bestaat uit vijf delen in deze volgorde:

• gecodeerde lengte
• content wordt voorafgegaan door het isgelijkteken (=)
• attribuutnaam
• gelijkteken (=) als scheidingsteken tussen naam en waarde
• attribuutwaarde, indien aanwezig.

Enkele voorbeelden van attributen (exclusief de gecodeerde lengteprefix):

=address=10.0.0.1

=disable-running-check=yes

De waarde kan gelijk (=) symbolen bevatten:

=name=iu=c3Eeg

De waarde mag leeg zijn:

=comment=

Houd er rekening mee dat de volgorde van attribuutwoorden en API parameters niet belangrijk is en dat u er niet op moet vertrouwen.

API-attribuutwoord

De structuur van een API-attribuutwoord ligt in een strikte volgorde:

• gecodeerde lengte
• content wordt voorafgegaan door het punt-teken (.)
• attribuutnaam
• gelijkteken (=) als scheidingsteken tussen naam en waarde
• attribuutwaarde

Momenteel is het enige dergelijke API-attribuut de tag.

Zoekwoord

Sentences kunnen aanvullende queryparameters bevatten die hun bereik beperken. Zie de query sectie voor details.

• Querywoorden beginnen met ?.
• Momenteel verwerkt alleen het commando print query words.

Voorbeeld van een sentence met query word-attributen:

/interface/print
?type=ether
?type=vlan
?#|!

Info De volgorde van de zoekwoorden is van belang

Antwoordwoord

Het wordt alleen door de router verzonden als reactie op de volledige zin die van de client is ontvangen.

• Het eerste woord van het antwoord begint met !.
• Elke verzonden sentence genereert ten minste één antwoord (als een verbinding niet wordt verbroken).
• Het laatste antwoord voor elke zin is het antwoord waarvan het eerste woord !done is.
• Fouten en uitzonderlijke situaties beginnen met !trap.
• Dataantwoorden beginnen met !re.
• Antwoorden van commando's die geen data hebben om mee te antwoorden, beginnen met !empty.
• Als de API verbinding moet worden gesloten, stuurt RouterOS een !fatal met een reden in de beschrijving en sluit daarna de verbinding.

Eerste aanmelding

• De client stuurt in het eerste bericht een gebruikersnaam en wachtwoord. In ons voorbeeld gebruiken we admin met een leeg wachtwoord:

  /login
  =name=admin
  =password=
  

  De router antwoordt met !done als de authenticatie is geslaagd.

• Het wachtwoord wordt in platte tekst verzonden.

• Als er een fout optreedt, bevat het antwoord =message=<error message>.

• Na een succesvolle login kan de client commando's gaan uitvoeren.

Tags

De API maakt het mogelijk om meerdere commando's tegelijk uit te voeren zonder te wachten tot het vorige is voltooid. Als de API-client dit doet en de commandoreacties moet kunnen onderscheiden, kan deze de parameter tag in de commandozinnen gebruiken.

Als een sentence een tag bevat, draagt elk antwoord op die sentence dezelfde tag-waarde.

Als u de parameter tag weglaat of leeg laat, bevatten de antwoorden op het commando geen tag-parameter.

Beschrijving van het commando

• /cancel

  • Optioneel argument: =tag=<tag of command to cancel>; zonder dit argument worden alle lopende commando's geannuleerd.
  • Annuleert zichzelf niet.
  • Alle geannuleerde commando's worden onderbroken en genereren gewoonlijk !trap- en !done-antwoorden.
  • Merk op dat /cancel een apart commando is en zijn eigen unieke parameter .tag kan hebben die geen verband houdt met het argument =tag van het commando.

• listen

  • Het commando listen is overal beschikbaar waar het CLI-commando print beschikbaar is, maar het werkt mogelijk niet overal.
  • !re-zinnen worden gegenereerd wanneer er iets verandert in een bepaalde itemlijst.
  • Wanneer een item wordt verwijderd of verdwijnt, bevat de !re-zin de waarde =.dead=yes.
  • Dit commando stopt niet uit zichzelf; gebruik het commando /cancel om het te beëindigen.

• getall

  • Het commando getall is overal beschikbaar waar het CLI-commando print beschikbaar is (getall is een alias voor print).
  • Antwoorden bevatten een =.id=<item internal number> eigenschap.

• print

  • Het API-commando print verschilt op de volgende manieren van de CLI-tegenhanger:
    • Het argument where wordt niet ondersteund; items kunnen worden gefilterd met query-woorden.
    • Het argument .proplist is een door komma's gescheiden lijst met eigenschapsnamen die in de teruggegeven items moeten worden opgenomen.
      • Teruggegeven items kunnen aanvullende eigenschappen hebben.
      • De volgorde van de teruggegeven eigenschappen is niet van belang en er kan niet op worden vertrouwd.
      • Als de lijst dubbele items bevat, is de afhandeling van die duplicaten ongedefinieerd.
      • Als een eigenschap in .proplist voorkomt maar ontbreekt bij een item, heeft dat item geen waarde voor die eigenschap (?name levert false op voor dat item).
      • Als .proplist ontbreekt, worden alle eigenschappen opgenomen zoals gevraagd door het print-commando, zelfs die met een trage toegangstijd (zoals bestandsinhoud en prestatietellers). Daarom wordt het gebruik van .proplist aangemoedigd. Het weglaten van .proplist kan een hoge prestatiestraf opleveren als het argument =detail= is ingesteld.

Queries

De commando's print en getall accepteren querywoorden die de set teruggegeven zinnen beperken.

• Querywoorden beginnen met ?.
• De volgorde van zoekwoorden is van belang. Een query wordt geëvalueerd vanaf het eerste woord.
• Een query wordt voor elk item in de lijst geëvalueerd. Als de query slaagt, wordt het item verwerkt; als een query faalt, wordt het item genegeerd.
• Een query wordt geëvalueerd met behulp van een stapel booleaanse waarden. In het begin bevat de stapel een oneindige hoeveelheid true-waarden. Als de stapel aan het einde van de evaluatie ten minste één false-waarde bevat, faalt de query.
• Zoekwoorden werken volgens de volgende regels:

Info Reguliere expressies worden niet ondersteund in de API, dus probeer geen query met het symbool ~ te versturen

Voorbeelden:

• Haal alle ethernet- en VLAN-interfaces op (equivalent aan het CLI-commando /interface/print where type=ether || type=vlan):

/interface/print
?type=ether
?type=vlan
?#|

• Haal alle routes op die een niet-lege comment hebben (equivalent aan het CLI-commando /ip/route/print where comment):

/ip/route/print
?>comment=

• Haal alle routes op die geen distance groter dan 1 hebben en waarvan de gateway gelijk is aan 172.16.1.1 (equivalent aan het CLI-commando /ip/route/print where !(distance>1 && gateway=172.16.1.1)):

/ip/route/print
?>distance=1
?gateway=172.16.1.1
?#&!

OID

Het commando print kan OID-waarden teruggeven voor eigenschappen die beschikbaar zijn in SNMP.

In de CLI kunnen OID-waarden worden bekeken door het commando print oid uit te voeren. In de API hebben deze eigenschappen namen die eindigen op .oid en kunnen ze worden opgehaald door hun namen toe te voegen aan de waarde van .proplist. Een voorbeeld:

/system/resource/print
=.proplist=uptime,cpu-load,uptime.oid,cpu-load.oid

De router stuurt een antwoord:

!re
=uptime=01:22:53
=cpu-load=0
=uptime.oid=.1.3.6.1.2.1.1.3.0
=cpu-load.oid=.1.3.6.1.2.1.25.3.3.1.2.1

!done

!trap

Wanneer een API-zin om welke reden dan ook mislukt, geeft de router een trap terug, vergezeld van een:

• Een message-attribuut dat meer details geeft over de fout.
• Een category-attribuut. Als de fout algemeen van aard is, geeft de router de foutcategorie terug. Mogelijke waarden voor dit attribuut zijn:
  • 0 - ontbrekend item of commando
  • 1 - fout in de argumentwaarde
  • 2 - uitvoering van commando onderbroken
  • 3 - fout gerelateerd aan scripting
  • 4 - een algemene fout
  • 5 - fout gerelateerd aan API
  • 6 - fout gerelateerd aan TTY
  • 7 - waarde gegenereerd met het :return-commando

/ip/address/add
=address=192.168.88.1
=interface=asdf

De router antwoordt met:

!trap
=category=1
=message=input does not match any value of interface

Bestaande items wijzigen

Net als zijn CLI-tegenhanger heeft de API een set-commando dat de ID van een item en de in te stellen parameters accepteert. De enige uitzondering is dat de API geen queries rechtstreeks bij het set-commando accepteert. Bijvoorbeeld het CLI-commando om de MTU-waarde op alle ethernet-interfaces in te stellen:

/interface set [find where type=ether] mtu=1500

Om hetzelfde met de API te bereiken, moet u eerst een print-query uitvoeren om de ID's te verkrijgen, en pas daarna het set-commando uitvoeren.

/interface/print
=.proplist=.id
?type=ether

De router antwoordt met:

!re
=.id=*1

!re
=.id=*2

Nu moet u door de geretourneerde ID's itereren en voor elk het commando set versturen:

/interface/set
=.id=*1
=mtu=1500

/interface/set
=.id=*2
=mtu=1500

Voorbeelden van commando's

/user/active/listen

/user/active/listen

!re
=.id=*68
=radius=no
=when=2006-10-24 08:40:42
=name=admin
=address=0.0.0.0
=via=console

!re
=.id=*68
=.dead=yes

... more !re sentences ...

/cancel, gelijktijdige commando's

Begin met luisteren naar interfacewijzigingen (tag is 2):

/interface/listen
.tag=2

Stuur een commando om de interface uit te schakelen (tag is 3):

/interface/set
=disabled=yes
=.id=ether1
.tag=3

De router antwoordt met !done op het commando disable (uitgevoerd met tag 3):

!done
.tag=3

Schakel de interface in (tag is 4):

/interface/set
=disabled=no
=.id=ether1
.tag=4

De client ontvangt van de router een update voor het listen-commando, gegenereerd door een wijziging van het eerste set-commando (uitgevoerd met tag 3):

!re
=.id=*1
=disabled=yes
=dynamic=no
=running=no
=name=ether1
=mtu=1500
=type=ether
.tag=2

Gevolgd door done voor het enable-commando (uitgevoerd met tag 4):

!done
.tag=4

Stuur een commando om de interfacelijst op te halen (tag is 5):

/interface/getall
.tag=5

De client ontvangt updates die zijn gegenereerd door een wijziging van het tweede set-commando (uitgevoerd met tag 4):

!re
=.id=*1
=disabled=no
=dynamic=no
=running=yes
=name=ether1
=mtu=1500
=type=ether
.tag=2

De client ontvangt antwoorden op het getall-commando (uitgevoerd met tag 5):

!re
=.id=*1
=disabled=no
=dynamic=no
=running=yes
=name=ether1
=mtu=1500
=type=ether
.tag=5

!re
=.id=*2
=disabled=no
=dynamic=no
=running=yes
=name=ether2
=mtu=1500
=type=ether
.tag=5

!done
.tag=5

Stop met luisteren - verzoek om het commando met tag 2 te annuleren, cancel zelf gebruikt tag 7:

/cancel
=tag=2
.tag=7

listen-commando is onderbroken (tag 2):

!trap
=category=2
=message=interrupted
.tag=2

cancel-commando is voltooid (tag 7):

!done
.tag=7

listen-commando is voltooid (tag 2):

!done
.tag=2

Voorbeeldclient

Een eenvoudige API-client in Python3

Voorbeelduitvoer met de oude inlogmethode:

debian@localhost:~/api-test$ ./api.py 10.0.0.1 admin ''
<<< /login
<<<
>>> !done
>>> =ret=93b438ec9b80057c06dd9fe67d56aa9a
>>>
<<< /login
<<< =name=admin
<<< =response=00e134102a9d330dd7b1849fedfea3cb57
<<<
>>> !done
>>>
/user/getall

<<< /user/getall
<<<
>>> !re
>>> =.id=*1
>>> =disabled=no
>>> =name=admin
>>> =group=full
>>> =address=0.0.0.0/0
>>> =netmask=0.0.0.0
>>>
>>> !done
>>>