Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
The project web site has an diff tool that compares the output of /console/inspect between RouterOS Versions.
Pre-build schema files for RouterOS REST API are available on this project's website at https://tikoci.github.io/restraml
Tip
File an issue in this project, if you'd like a specific version built.
Included are three files:
- RAML - schema in RAML 1.0 format, used in tools like Postman
- HTML - documentation, generated from the schema
- OAS2 - OpenAPI 2.0 format, converted from RAML
- JSON - intermediate raw data from RouterOS's /console/inspect in JSON format, for use with data analytics
- MIB - link to official Mikrotik MIB for SNMP
There may be a base and +extra schema download links.
- The base schema is just the routeros.npk package
- The +extra schema contains all X86 packages, including base, plus "extra-packages": routeros, dude, container, rose-storage, gps, lora, calea, user-manager, routeros, ups, iot, wifiwave2, tr069-client
For detailed instructions on using the RAML schema with Postman, see this forum article: https://forum.mikrotik.com/viewtopic.php?p=1041886
Warning
Ironically, the RouterOS schema uncovered a bug in the most recent version of Postman that does not allow directly importing a RAML schema. Postman is working on a fix. Any existing loaded schema still works. Postman version 11.0.12 and below work fine.
To import this schema into Postman App 11.1.14 or greater, the RAML schema must be indirectly as an "API", and then from API creating a collection from the API - rather than directly importing the RAML, see raml1-to-postman issue #84 showing the process, including a video of the process.
OpenAPI 2.0 schema RouterOS REST API is available on Downloads tagged as OAS2. The OpenAPI schema is generated from the RAML schema. Only +extra schema version is available.
Should OpenAPI 3.0 (OAS3) be needed, this can be done using MuleSoft's online converter here: https://mulesoft.github.io/oas-raml-converter However, the OAS3 produced does not validate using webapi-parser tool, but will load in Postman.
Tip
Generally, if a RAML schema is supported by your tool, use RAML schema as other formats may be further losy.
- Install Bun
- Clone this repository
- Install js-yaml: bun install js-yaml
- Run rest2raml.js like so:
URLBASE=https://<IP or DNS name>/rest BASICAUTH=<user>:<pass> bun rest2raml.js
# Example:
URLBASE=https://192.168.88.1/rest BASICAUTH=admin:h3llow0rld bun rest2raml.jsWait a while for this code to run. It could take as long as an hour to process the entire schema. 5. Open a pull request to add the RAML file to this repository if it's missing 😉
- Follow steps 1-2 above, or 1-4 if this repository doesn't currently contain a RAML file for your RouterOS version.
- Install raml2html and raml2html-slate-theme: bun install raml2html raml2html-slate-theme
- Generate the HTML page with raml2html:
raml2html --theme raml2html-slate-theme <RAML file> > <HTML file>
# Example:
raml2html --theme raml2html-slate-theme ros-rest-all.raml > ros-rest.all.htmlThe schema generation is done via JavaScript, specifically using bun, in rest2raml.js. The code connects to RouterOS via REST API, to use the /console/inspect command to traverse the "AST" for RouterOS config. The results of this intermediate phase are stored in an inspect.json, as retrieved from the router. With the inspect.json, rest2raml.js then builds that data into a RAML schema for API tools.
Warning
The generated schema is more for convenience than validation. Generation is limited to the data available from /console/inspect, and what's reasonable to deduce. So there is not perfect fidelity between schema and API. For example, while there are required and optional parameters, all parameters are marked as optional in the schema. As a result, all attributes are generally shown - while using all of them is likely to be invalid.
GitHub Actions is used to build the schema published on this project's website:
- Builds for manual-from-docker-in-docker.yaml Workflow - start a RouterOS CHR (via docker-compose and QEMU) within the build, and then rest2raml.js uses the "internal" CHR to generate the schema, without any external resources needed.
- Builds for manual-from-extra-docker-in-docker.yaml Workflow - same as above, except CHR is loaded with extra-packages prior to schema generation
- Builds for manual-from-secrets.yaml Workflow - uses GitHub Secret with information to connection to a RouterOS device on internet
Note
All actions use only workflow_dispatch, so new generation is still manually triggered by providing a version on the Action page in GitHub. Only the repo owner can do this.
The website for the project - with downloadable schemas – is from the /docs directory in repo.