Přehled
Termín "REST API" obecně označuje rozhraní API, ke kterému se přistupuje prostřednictvím protokolu HTTP na předem definované sadě adres URL orientovaných na zdroje.
Od verze RouterOS v7.1beta4 je implementováno jako obalové rozhraní JSON konzolového rozhraní API. Umožňuje vytvářet, číst, aktualizovat a mazat prostředky a volat libovolné konzolové příkazy.
Chcete-li začít používat rozhraní REST API, musí být nakonfigurována a spuštěna služba www-ssl [odkaz na služby IP]. Je-li služba SSL povolena, lze ke službě REST přistupovat připojením na adresu https://<routers_IP>/rest.
Nejjednodušší způsob, jak začít, je použít cURL, wget nebo jiného klienta HTTP, dokonce i nástroj RouterOS fetch.
Kód: Vybrat vše
$ curl -k -u admin: https://10.155.101.214/rest/system/resource
[{"architecture-name":"tile","board-name":"CCR1016-12S-1S+",
"build-time":"Dec/04/2020 14:19:51","cpu":"tilegx","cpu-count":"16",
"cpu-frequency":"1200","cpu-load":"1","free-hdd-space":"83439616",
"free-memory":"1503133696","platform":"MikroTik",
"total-hdd-space":"134217728","total-memory":"2046820352",
"uptime":"2d20h12m20s","version":"7.1beta4 (development)"}]
Autentizace
Ověřování k rozhraní REST API se provádí pomocí HTTP Basic Auth. Zadejte uživatelské jméno a heslo stejné jako pro uživatele konzole (ve výchozím nastavení "admin" bez hesla).
Formát JSON
Server se v zásadě řídí standardem ECMA-404 s následujícími poznámkami:
- V odpovědích JSON jsou všechny hodnoty objektů kódovány jako řetězce, i když jsou podkladovými daty čísla nebo logické hodnoty.
- Server také přijímá čísla v osmičkovém formátu (začíná 0) a šestnáctkovém formátu (začíná 0x). Pokud jsou čísla zasílána ve formátu řetězce, předpokládá se, že jsou v desítkovém formátu.
- Čísla s exponenty nejsou podporována.
Metody HTTP
Níže je uvedena tabulka shrnuje podporované metody HTTP.
| HTTP Verv | CRUD | ROS | Popis |
|---|---|---|---|
| GET | Read | Získání záznamů | |
| PATCH | Update/Modify | set | Aktualizace jednoho záznamu |
| PUT | Create | add | Vytvoření nového záznamu |
| DELETE | Delete | remove | Smazání jednoho záznamu |
| POST | Univerzální metoda pro získání přístupu ke všem konzolovým příkazům |
Formát adresy URL
GET
Tato metoda umožňuje získat seznam všech záznamů nebo jeden záznam ze zadané nabídky zakódované v adrese URL.
Například získat všechny IP adresy (ekvivalentní příkazu 'ip/adresa/print' z CLI):
Kód: Vybrat vše
$ curl -k -u admin: https://10.155.101.214/rest/ip/address
[{".id":"*1","actual-interface":"ether2","address":"10.0.0.111/24","disabled":"false",
"dynamic":"false","interface":"ether2","invalid":"false","network":"10.0.0.0"},
{".id":"*2","actual-interface":"ether3","address":"10.0.0.109/24","disabled":"true",
"dynamic":"false","interface":"ether3","invalid":"false","network":"10.0.0.0"}]
Kód: Vybrat vše
$ curl -k -u admin: https://10.155.101.214/rest/ip/address/*1
{".id":"*1","actual-interface":"ether2","address":"10.0.0.111/24","disabled":"false",
"dynamic":"false","interface":"ether2","invalid":"false","network":"10.0.0.0"}
Kód: Vybrat vše
$ curl -k -u admin: https://10.155.101.214/rest/interface/ether1
Kód: Vybrat vše
$ curl -k -u admin: "https://10.155.101.214/rest/ip/address?network=10.155.101.0&dynamic=true"
[{".id":"*8","actual-interface":"sfp12","address":"10.155.101.214/24","disabled":"false",
"dynamic":"true","interface":"sfp12","invalid":"false","network":"10.155.101.0"}]
Kód: Vybrat vše
$ curl -k -u admin: 'https://10.155.101.214/rest/ip/address?comment=test&interface=dummy'
[{".id":"*3","actual-interface":"dummy","address":"192.168.99.2/24","comment":"test",
"disabled":"false","dynamic":"false","interface":"dummy","invalid":"false","network":"192.168.99.0"}]
Kód: Vybrat vše
$ curl -k -u admin: https://10.155.101.214/rest/ip/address?.proplist=address,disabled
[{"address":"10.0.0.111/24","disabled":"false"},{"address":"10.0.0.109/24","disabled":"true"}]
PATCH
Tato metoda se používá k aktualizaci jednoho záznamu. Nastavte tělo volání PATCH jako objekt JSON, který obsahuje pole a hodnoty aktualizovaných vlastností. Například přidání komentáře:
Kód: Vybrat vše
Kód: Vybrat vše
$ curl -k -u admin: -X PATCH https://10.155.101.214/rest/ip/address/*3 \
--data '{"comment": "test"}' -H "content-type: application/json"
{".id":"*3","actual-interface":"dummy","address":"192.168.99.2/24","comment":"test",
"disabled":"false","dynamic":"false","interface":"dummy","invalid":"false","network":"192.168.99.0"}
PUT
Metoda slouží k vytvoření nových záznamů v nabídce zakódované v adrese URL. Tělo by mělo být nastaveno jako objekt JSON obsahující parametry použité na nově vytvořený záznam.
V případě úspěchu server vrátí vytvořený objekt se všemi parametry.
V rámci jednoho požadavku lze vytvořit pouze jeden prostředek.
Například přidání IP adresy do fiktivního rozhraní:
Kód: Vybrat vše
$ curl -k -u admin: -X PUT https://10.155.101.214/rest/ip/address \
--data '{"address": "192.168.111.111", "interface": "dummy"}' -H "content-type: application/json"
{".id":"*A","actual-interface":"dummy","address":"192.168.111.111/32","disabled":"false",
"dynamic":"false","interface":"dummy","invalid":"false","network":"192.168.111.111"}
DELETE
Tato metoda slouží k odstranění záznamu se zadaným ID z nabídky zakódované v adrese URL. Pokud se smazání podařilo, server odpoví prázdnou odpovědí. Například volání pro odstranění záznamu dvakrát, při druhém volání router vrátí chybu 404:
Kód: Vybrat vše
$ curl -k -u admin: -X DELETE https://10.155.101.214/rest/ip/address/*9
$ curl -k -u admin: -X DELETE https://10.155.101.214/rest/ip/address/*9
{"error":404,"message":"Not Found"}
POST
Všechny funkce rozhraní API jsou k dispozici prostřednictvím metody POST. Příkazové slovo je zakódováno v hlavičce a volitelné parametry jsou předávány v objektu JSON s odpovídajícími poli a hodnotami. Chcete-li například změnit heslo aktivního uživatele, odešlete příkaz
Kód: Vybrat vše
POST https://router/rest/password
{"old-password":"old","new-password":"N3w", "confirm-new-password":"N3w"}
- Pokud odpověď obsahuje věty '!re' (záznamy), bude odpověď JSON obsahovat seznam objektů
- Pokud věta "!done" obsahuje data, bude odpověď JSON obsahovat objekt s daty
- Pokud věta "!done" neobsahuje žádné záznamy ani data, bude odpověď obsahovat prázdný seznam
Proplist
The '.proplist' key is used to create .proplist attribute word. The values can be a single string with comma-separated values:
Kód: Vybrat vše
POST https://router/rest/interface/print
{".proplist":"name,type"}
Kód: Vybrat vše
POST https://router/rest/interface/print
{".proplist":["name","type"]}
Kód: Vybrat vše
$ curl -k -u admin: -X POST https://10.155.101.214/rest/ip/address/print\
--data '{"_proplist": ["address","interface"]}' -H "content-type: application/json"
[{"address":"192.168.99.2/24","interface":"dummy"},
{"address":"172.16.5.1/24","interface":"sfpplus1"},
{"address":"172.16.6.1/24","interface":"sfp2"},
{"address":"172.16.7.1/24","interface":"sfp3"},
{"address":"10.155.101.214/24","interface":"sfp12"},
{"address":"192.168.111.111/32","interface":"dummy"}]
Query
Klíč '.query' se používá k vytvoření zásobníku dotazů. Hodnotou je seznam slov dotazu. Například tento požadavek POST :
Kód: Vybrat vše
POST https://router/rest/interface/print
{".query":["type=ether","type=vlan","#|!"]}
Kód: Vybrat vše
/interface/print
?type=ether
?type=vlan
?#|!
Kód: Vybrat vše
$ curl -k -u admin: -X POST https://10.155.101.214/rest/ip/address/print \
--data '{".proplist": [".id","address","interface"], ".query": ["network=192.168.111.111","dynamic=true","#|"]}'\
-H "content-type: application/json"
[{".id":"*8","address":"10.155.101.214/24","interface":"sfp12"},
{".id":"*A","address":"192.168.111.111/32","interface":"dummy"}]
Časový limit
Pokud příkaz poběží neomezeně dlouho, dojde k vypršení časového limitu a připojení se ukončí s chybou. Aktuální interval timeoutu je 60 sekund. Chcete-li se vyhnout chybám timeoutu, přidejte parametr, který by dostatečně omezil dobu provádění příkazu.
Podívejme se například, co dostaneme, když příkaz ping překročí časový limit, a jak tomu zabránit přidáním parametru count:
Kód: Vybrat vše
$ curl -k -u admin: -X POST https://10.155.101.214/rest/ping \
--data '{"address":"10.155.101.1"}' \
-H "content-type: application/json"
{"detail":"Session closed","error":400,"message":"Bad Request"}
$ curl -k -u admin: -X POST https://10.155.101.214/rest/ping \
--data '{"address":"10.155.101.1","count":"4"}' \
-H "content-type: application/json"
[{"avg-rtt":"453us","host":"10.155.101.1","max-rtt":"453us","min-rtt":"453us","packet-loss":"0","received":"1","sent":"1","seq":"0","size":"56","time":"453us","ttl":"64"},
{"avg-rtt":"417us","host":"10.155.101.1","max-rtt":"453us","min-rtt":"382us","packet-loss":"0","received":"2","sent":"2","seq":"1","size":"56","time":"382us","ttl":"64"},
{"avg-rtt":"495us","host":"10.155.101.1","max-rtt":"650us","min-rtt":"382us","packet-loss":"0","received":"3","sent":"3","seq":"2","size":"56","time":"650us","ttl":"64"},
{"avg-rtt":"461us","host":"10.155.101.1","max-rtt":"650us","min-rtt":"359us","packet-loss":"0","received":"4","sent":"4","seq":"3","size":"56","time":"359us","ttl":"64"}]
Kód: Vybrat vše
$ curl -k -u admin: -X POST 'https://10.155.101.214/rest/tool/bandwidth-test' \
--data '{"address":"10.155.101.1","duration":"2s"}' \
-H "content-type: application/json"
[{".section":"0","connection-count":"20","direction":"receive","lost-packets":"0",
"random-data":"false","rx-10-second-average":"0","rx-current":"0","rx-size":"1500",
"rx-total-average":"0",
"status":"connecting"},
{".section":"1","connection-count":"20","direction":"receive","duration":"1s",
"lost-packets":"0","random-data":"false","rx-10-second-average":"0","rx-current":"0",
"rx-size":"1500","rx-total-average":"0",
"status":"running"},
{".section":"2","connection-count":"20","direction":"receive","duration":"2s",
"lost-packets":"581175","random-data":"false","rx-10-second-average":"854372352",
"rx-current":"854372352","rx-size":"1500","rx-total-average":"854372352",
"status":"running"},
{".section":"3","connection-count":"20","direction":"receive","duration":"3s",
"lost-packets":"9014","random-data":"false","rx-10-second-average":"891979008",
"rx-current":"929585664","rx-size":"1500","rx-total-average":"891979008",
"status":"done testing"}]
Chyby
Úspěšnost nebo neúspěšnost volání API je indikována stavovým kódem HTTP. V případě selhání (stavový kód 400 nebo větší) obsahuje tělo odpovědi objekt JSON s kódem chyby, popisem chyby a volitelnými podrobnostmi o chybě. Například při pokusu o odstranění rozhraní se vrátí následující údaje
Kód: Vybrat vše
{"error":406,"message":"Not Acceptable","detail":"no such command or directory (remove)"}