Device delete REST API returns 202

[Nathan Sowatskey]

Hi

The attached image shows the response when using a the Delete API for a device given its ID.

Note that the response is 202, which is generally defined as "accepted". See: https://httpstatuses.com/202

The 202 is NOT one of the Error Status Codes defined in the API documentation. Further note that 200 is one of those codes, bit is not an "error" code per se.

It is not clear what 202 actually means here, as it is not explicitly documented.

Regards

Nathan

[aradford]

Just about all (/file is exception) API on APIC-EM are async.  This is a common pattern.  You get a 202 and a taskId.  This blog post shows an example of how this works..

Cisco Live Springboard Event Rocks The House!https://communities.cisco.com/community/developer/dna/blog/2016/07/13/cisco-live-springboard-event-rocks-the-house

You need to do a GET on /api/task/<taskId> to find out the status of the DELETE/POST/PUT

This is a fundamental concept of the controller API.

Cisco Live Springboard Event Rocks The House!

[Nathan Sowatskey]

Adam

Thank you for following up.

I think that the main point here is that the Swagger API pages are perhaps not a good guide to how the APIs should be used.

Some suggested improvements are:

- Change "Error Status Codes" to "Response Status Codes"

- Document the 202 response in the table of response codes with words to the effect of: "202 - Request is being processed. Use  /task/{taskId} to get task status."

- Provide general guidance as to the async task based nature of the API from a link that is clearly visible from the Swagger API pages

Regards

Nathan

[Nathan Sowatskey]

Interestingly, the POST /network-device/location Swagger page does seem to document how tasks are used with APIs properly. So some of the API pages are correct, but not all.

Regards

Nathan