Inaccurate Swagger description for ipam_prefixes_available-ips_create API call

[tomasherout]

Environment

• Python version: 3.7.9
• NetBox version: 2.9.6

Steps to Reproduce

1. Look at Swagger definition of response for API call ipam_prefixes_available-ips_create:

=> it's described as returns array of objects AvailableIP type

2. make POST request to /api/ipam/prefixes/${subnetID}/available-ips/ and look to response. It's inconsistent with definition:

2.1.: It should be return array, in the fact it returns object.
2.2: Family attribute is described as integer, but server returns object
2.3: It returns id, url, role and lot of other

Expected Behavior

Fixed Swagger description.

Observed Behavior

API call return object on top level:

It does not correspond to swagger definition of response. Object properties also does not match.

[DanSheps]

This serializer can report many or only a single address back.

We should probably return a consistent result no matter what, so I think this should return an array, but I will let others comment as well.

[tomasherout]

Create operation returns only one or nothgin. List operation only can return more ...

[jeremystretch]

Create operation returns only one or nothgin. List operation only can return more ...

Yes, that's what Dan said. This is intentional behavior, provided for the convenience of the API consumer. I don't see a reason to change it.

[tomasherout]

Incorrect Swagger description causes generated clients like https://github.com/netbox-community/go-netbox unusable for that call.

Can you say me in which case ipam_prefixes_available-ips_create (POST /api/ipam/prefixes/${prefix.id}/available-ips/) return array of objects with fields family, address, VRF?

[jeremystretch]

The relevant code is here for your review.

[tomasherout]

After code inspection it's clear that API also accept array as input a then response is also array.

From Swagger point of view is not make sense - in case, when object is input, then object is result, not array.

I think could be correct change

netbox/netbox/ipam/api/views.py

Line 168 in 87c13a8

request_body=serializers.AvailableIPSerializer(many=False))

to many=True (it's universal)

Otherwise, generated API clients does not work.

BTW: in GraphQL schema is not possible do things like this because it's really not good idea.

[jeremystretch]

Otherwise, generated API clients does not work.

This is not a primary concern for us. My primary concern is how easy the REST API is for the user to consume. Supporting both single- and multi-object requests via the same endpoint is more convenient for the end user, so that's the approach we've taken.

[tomasherout]

But fix is related to Swagger metadata only. There is no change for user and API capability to accept & return of object and arrays.

[jeremystretch]

@tomasherout would you like to volunteer to own this issue?

[tomasherout]

I can try it