Improve the openapi definition of custom_fields

[smutel]

Environment

• Python version: 3.5.2
• NetBox version: 2.6.7

Proposed Functionality

Currently custom_fields are described as below in the swagger.json:

"custom_fields": {                                                      
  "title": "Custom fields",
  "type": "object"
},  

We this kind of definition, it's not easy to parse code retrieved from the api. In particular to develop a terraform provider or to use this plugin for openapi: https://github.com/dikhan/terraform-provider-openapi.

The author of this plugin suggest to define custom_fields as below:

"custom_fields":
  "title": "Custom fields",  
  "type": "array"
    "items":
      $ref: '#/definitions/custom_fields'

  "custom_field":
    "type": "object"
    "properties":
      "property_name":
        "type": "string"
      "property_type":
        "type": "string"
      "property_value":
        "type": "string"

Use Case

• Make easy the code to use this part of this API
• Automation

Database Changes

I don't think so that a dabase change is needed.

External Dependencies

Don't know.

[kobayashi]

Do want to add custom fields through api? or let me know more specific use case for this?

[smutel]

Creating a terraform provider for netbox.

[kobayashi]

Nice! Is it related to change the scheme though? If that would be recommendation from your reference, please let me clear reason why that is recommended. Sorry but I am not familiar much with how to create a terraform provider.

[saper]

It looks more complex like this - custom fields can have 6 types. For example, a boolean field will be returned by API like this:

    "custom_fields": {
        "test_field": null
      },

This will not work with something like name/value

[saper]

The question is - should swagger API definition change every time we add/delete a custom field?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. NetBox is governed by a small group of core maintainers which means not all opened issues may receive direct feedback. Please see our contributing guide.

[lampwins]

The question is - should swagger API definition change every time we add/delete a custom field?

My take on this is yes. In NetBox methodology, custom fields are a part of the model schema and realistically change infrequently.

We could do this with a custom field inspector but the problem is it would require a DB query to get the field definitions. It has been proposed in the past that we switch the schema to be served as static content instead of being rendered on the fly, which would probably make this more feasible.

[saper]

It has been proposed in the past that we switch the schema to be served as static content instead of being rendered on the fly, which would probably make this more feasible.

Thank you. This makes perfect sense. An additional advantage of static API definitions is that it might be easier to version them - it should be possible to understand when and why the API has changed.

This opens up a (remote) possibility to support multiple versions of API in the future at the same time.

(We are considering opening up netbox API to a wide range of internal consumers and it would be great to have ability to control the stability of the interface definitions somehow).

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. NetBox is governed by a small group of core maintainers which means not all opened issues may receive direct feedback. Please see our contributing guide.

[stale[bot]]

This issue has been automatically closed due to lack of activity. In an effort to reduce noise, please do not comment any further. Note that the core maintainers may elect to reopen this issue at a later date if deemed necessary.