Page 1 of 1

REST API schema for Postman & more

Posted: Mon Sep 11, 2023 6:20 am
by Amm0
While not "scripting", I had a JavaScript implementation that using /system/console via REST to generate a RAML 1.0 scheme. I just hadn't written it up here, so here it is.

It isn't exactly 100%, perhaps 90%. e.g.
- especially the arguments – and like ChatGPT – it may make a few — but most should work, especially POST ones.
- in most cases, it it's NOT picky on types – most are marked an "any".
- there BUGS in /console/inspect using request=syntax – some crash so not a lot of "syntax" data is used
- has all packages, except calea
- return attributes are "inexact" – it just marked as "any" JSON
- arguments are generally list (perhaps not in all cases), but again types are "any"
- since it's automatically generated, there are no "examples" or "documentation" in schema – just endpoints and args
- GET is not fully specified for root commands (GET /ip/address) – it should show query params and array output
- some postman-defaults could be better, but unsure how to control via RAML...
- likely others...

Anyway still good start to a more formalized schema. While not directly OpenAPI/swagger, the RAML imports into postman just fine.

RAML Schema for Download
The generated RAML schema for import (~6MB, 250K lines of YAML) can be download from:
Check the website for new ones.

Newer version are on the GitHub project but orginal files from time of this posting remain:
7.12 -
7.13 -

Using Postman... (and other HTTP tools)


For use in Postman
1. Go to API section
2. Click "Import" button on near top of API section
3. Upload the RAML file from above:
4. Click "View import setting", selecting "Schema" – NOT the default "example" — as source for postman request/response data:
5. Hit back icon in upper left, then click "Import"
6. Wait... (postman shows progress in status bar)
7. Go to "Collections" section on left side of Postman, and notice the new RouterOS one
8. Using postman is more up-to-you... at least the following need to be added by user for it call REST API on a RouterOS device:
- "Basic Auth" should be set either on collection (or elsewhere)
- {{baseUrl}} needs to be set to your router's IP using the environment variables in postman

Converting RAML to OpenAPI / swagger formats

This web site seem to take a RAML schema, and get then an OpenAPI schema from it:
which gets an OpenAPI formatted scheme from RAML.

Generated OpenAPI Schema ... napi3.json

Although I didn't test it much, it does seems to load in Postman at least.

I'm sure there other CLI tools to do same, but RAML is support by postman which was concern.

JavaScript to generate RAML
Mainly for reference. It takes ~30 minutes, to make 30K+ REST calls, on beefy MacBook.... JS source code is in a GitHub project:
Not the pretty code, but works. I'll leave containering for it for another day

Note: I would have used RouterOS script, but the 4K chucks of 6MBs didn't sound fun – but yes a RSC script, or a container, theoretically work here too. Just JS was easier/quicker since I'd done most of it a while back.

Postman in VSCode with RouterOS REST...
Using the VSCode extension for Postman also works, once the schema has been loaded:
Including postman's code generation from REST schema:

- added TODO
- fixed references to use GH project instead of a git for RAML schema download
- add screenshot of VSCode with postman plugin
- updated URL to generate OpenAPI schema
- updated to reference GitHub project.

Re: REST API schema (using RAML) for Postman

Posted: Mon Sep 11, 2023 5:36 pm
by Amm0
I generated some HTML docs using the generated RAML scheme.

Generated REST API Docs

If you want to see what options are available from the REST API, this at at least shows the URL and most parameters for each endpoint.

- descriptions are limited since "/console/inspect request=syntax" fails on some path='s. If that's fixed, there be some descriptions.

Re: REST API schema (using RAML) for Postman

Posted: Tue Sep 12, 2023 9:39 am
by JDF
Great work! This will be very useful.

Re: REST API schema (using RAML) for Postman

Posted: Tue Sep 12, 2023 8:06 pm
by Amm0
It's a start, but still needs some work... At some point I'll fix this up a bit more. I'd only done POST the GET/PATCH/DELETE methods I just quickly hacked in, but got messy.

I did convert the RAML to OpenAPI, but didn't verify it, but might be helpful since more REST tools support OpenAPI. The RAML converted to OpenAPI schema format it's here: ... napi3.json

In case it wasn't clear, schema shows all possible request parameters for HTTP endpoints. In most cases, you just a need a few & providing ALL parameters may actually NOT be valid syntax. Since goal was to know the possible options...not provide ready-to-use examples.

The current scheme is pretty vague on possible JSON responses JSON. In theory, it be possible to extract possible responses (e.g. other than just it's an object or array as in current schema). In particular for GET's it can likely know the attributes in the JSON response. Similarly it probably can do more to pull out some descriptions. Basically the "tree of commands" should be complete, at least for the router/version it was extracted.

But extracting "metadata" from "request=syntax ..." gets trickier since whole scheme in /console/inspect command is undocumented. But all the data is based on /console/inspect... if curious on how that works, see: viewtopic.php?t=199139#p1024410 – I don't actually use all of the possible data in there today.

Re: REST API schema for Postman & more

Posted: Thu Dec 14, 2023 11:04 pm
by brotherdust
Would be nice if MikroTik would just publish a spec instead of making you do all the hard work.

I begged them not to use a custom REST API and instead use the de-facto YANG standard. That way the router configuration could be authored and stored in a vendor-neutral format and transformed into something RouterOS can understand.

It’s sad they said no. Your solution here makes me less sad, and for that I am very grateful. If you’d like some help, in the form of technical docs, test setup, etc, hit me up on GitHub

Re: REST API schema for Postman & more

Posted: Wed May 22, 2024 10:45 pm
by Amm0
I automated schema generation on GitHub. And added a new download page that shows schema/docs for a variety of versions from 7.9 to 7.15rc4:

The source and other details are here:
GitHub Project:
VSCode Online View:

Geeky Details... The internals of the automation are kinda nifty (IMO) & likely useful other automation using GitHub+RouterOS needs. Specifically, the GitHub Action that builds schemas/docs/etc, runs a CHR inside itself GitHub, that's used to make the need REST calls to /console/inspect. The GitHub project, specifically "Actions" shows all the gory details how the schemas are generated, with the manual-docker-in-docker.yaml doing the heavy lifting here.

Would be nice if MikroTik would just publish a spec instead of making you do all the hard work.
Very true. When I started this mini-project... I just wanted to "diff" the command tree to see what changed in CLI between versions. And... got needing to run Docker^2+QEMU+CHR somehow...

Re: REST API schema for Postman & more

Posted: Fri May 24, 2024 6:20 pm
by Amm0
I just wanted to "diff" the command tree to see what changed in CLI between versions. And... got needing to run Docker^2+QEMU+CHR somehow...
I added a `diff` UI to the Schema Download page on GitHub,

It will show what commands/attributes have changed between RouterOS Versions:
Screenshot 2024-05-24 at 7.56.12 AM.png