REST API definition (OpenAPI spec)

Products cnMaestro
1

Hello,

We are doing network automation work for our clients and the cnMaestro REST API has been a huge help. Recently I dug into the deployment and found that there is an included OpenAPI spec. I tried to use it to generate clients that would ease our job to communicate with cnMaestro but I stumbled upon several errors in the definition. I understand that since it’s not provided in the downloads, it probably isn’t supported but you may want to fix them anyway.

  1. In OpenAPI v3 there is no ‘null’ type as used in build/device/configuration/enterprise_wifi/wlan_definitions.yaml at line 113 and many other places. See here. Instead there is the nullable field. In this example the time_range should be defined as follows:
time_range:
  description: 'Time range in the format "HH:MM-HH:MM"'
  type: string
  pattern: >-
          ^((?:[01]\d:[0-5][0-9]|2[0-3]:[0-5][0-9])(?:\s?)-(?:\s?)(?:[01]\d:[0-5][0-9]|2[0-3]:[0-5][0-9]))$
  nullable: true
  1. The schema object cannot contain an array as in schemas/guest_portal.yaml at line 66. It should be:
schema:
  $ref: '../build/guest_portal.yaml#/Api.V1.PUT.Services.wifi-enterprise.Guest_Access.Portals/body'
  1. In schemas/guest_portal.yaml line 50, the definition of the array is missing. As per the schema definition, if the type is array then an items object must be present. For example:
properties:
  whitelist:
    type: array
    items:
      type: string
  1. In the OAuth security scheme definition, the scopes field is missing but it is required on the spec.
  2. Typos: the word description is mistyped as descripton or desription or descriptin in some files. The word default is mistyped as defauilt.
  3. You cannot augment the definition of a referenced object as in build/device/configuration/enterprise_wifi/ap_group.yaml line 35. Items of allOf must be schema definition but this required is not. Similar case in build/device/configuration/enterprise_wifi/ap_group_definitions.yaml line 1727.
  4. The producers field defined in several files does not exist in the spec. It probably is a leftover from Swagger v2 produces.
  5. There are no schemas defined for any data returned by cnMaestro. Thus the data returned cannot be parsed by generated clients.

It would be really nice and helpful if you released the OpenAPI spec since you’ve done most of the work to develop it anyway.

2 Likes
2

Hi babis_k,

Thank you for reporting this with such a thorough explanation! It is very clear what is wrong. I’ve added these issues to our bug tracker to be fixed in an upcoming release.

Besides these OpenAPI issues, how useful are you finding the API?

3

Thanks!
The API in general is very helpful and very well documented. We do both configuration and monitoring through it. We started using it since it was read-only (version 1.6 I think). But following up in version updates is cumbersome, that’s why I investigated the OpenAPI.

I wish you provided it on the cloud too. Some clients would like to use it but we are sticking on-prem due to the API.

1 Like