Community discussions

MikroTik App
 
User avatar
Amm0
Forum Guru
Forum Guru
Topic Author
Posts: 3706
Joined: Sun May 01, 2016 7:12 pm
Location: California

REST API schema for Postman & more

Mon Sep 11, 2023 6:20 am

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:
https://tikoci.github.io/restraml
Check the website for new ones.


Newer version are on the GitHub project but orginal files from time of this posting remain:
7.12 - https://tikoci.github.io/restraml/routeros.raml
7.13 - https://tikoci.github.io/restraml/routeros.7.13.raml


Using Postman... (and other HTTP tools)

Image

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:
Image
4. Click "View import setting", selecting "Schema" – NOT the default "example" — as source for postman request/response data:
Image
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:
https://mulesoft.github.io/oas-raml-converter/
which gets an OpenAPI formatted scheme from RAML.

Generated OpenAPI Schema
https://tikoci.github.io/restraml/route ... 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:
https://github.com/tikoci/restraml
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:
Image
Including postman's code generation from REST schema:
Image
Image

edits:
- 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.
Last edited by Amm0 on Thu May 30, 2024 10:44 pm, edited 11 times in total.
 
User avatar
Amm0
Forum Guru
Forum Guru
Topic Author
Posts: 3706
Joined: Sun May 01, 2016 7:12 pm
Location: California

Re: REST API schema (using RAML) for Postman

Mon Sep 11, 2023 5:36 pm

I generated some HTML docs using the generated RAML scheme.

Generated REST API Docs
https://tikoci.github.io/restraml/

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.

Notes:
- descriptions are limited since "/console/inspect request=syntax" fails on some path='s. If that's fixed, there be some descriptions.
 
JDF
just joined
Posts: 12
Joined: Wed Aug 16, 2023 1:40 pm

Re: REST API schema (using RAML) for Postman

Tue Sep 12, 2023 9:39 am

Great work! This will be very useful.
 
User avatar
Amm0
Forum Guru
Forum Guru
Topic Author
Posts: 3706
Joined: Sun May 01, 2016 7:12 pm
Location: California

Re: REST API schema (using RAML) for Postman

Tue Sep 12, 2023 8:06 pm

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 originally...so 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: https://tikoci.github.io/restraml/route ... 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.
 
brotherdust
Member Candidate
Member Candidate
Posts: 130
Joined: Tue Jun 05, 2007 1:31 am

Re: REST API schema for Postman & more

Thu Dec 14, 2023 11:04 pm

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 https://github.com/brotherdust
 
User avatar
Amm0
Forum Guru
Forum Guru
Topic Author
Posts: 3706
Joined: Sun May 01, 2016 7:12 pm
Location: California

Re: REST API schema for Postman & more

Wed May 22, 2024 10:45 pm

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:
Downloads: https://tikoci.github.io/restraml

The source and other details are here:
GitHub Project: https://github.com/tikoci/restraml
VSCode Online View: https://github.dev/tikoci/restraml

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...
 
User avatar
Amm0
Forum Guru
Forum Guru
Topic Author
Posts: 3706
Joined: Sun May 01, 2016 7:12 pm
Location: California

Re: REST API schema for Postman & more

Fri May 24, 2024 6:20 pm

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, https://tikoci.github.io/restraml

It will show what commands/attributes have changed between RouterOS Versions:
Screenshot 2024-05-24 at 7.56.12 AM.png
You do not have the required permissions to view the files attached to this post.

Who is online

Users browsing this forum: No registered users and 5 guests