[IoT Central] REST API Review (2022-05-31)

yang-hai-feng commented 2 years ago

Service name IoT Central

Whether this is a new or existing API Existing API

Whether or not your service already been deployed No, TBD by end of May

A brief description of the material to be reviewed/changed (added from 1.0, same as 1.2-preview)

Device Group List, Get, Create, Update and Delete.
Organization List, Get, Create, Update and Delete.
Organization in Users, Devices, Device Groups.
File Upload Configuration support
Correct consume for all existing versions, there is no support for application/json-patch+json in current production, we only support application/json and application/json-merge-patch+json in our production, the old swagger is wrong.

markweitzel commented 2 years ago

API Stewardship Board Review - 18-May-22

Remove the maxItems from the Device. This will be a bit more future proof.
- This should be well documented in the swagger. Check the build pipeline for the generated docs. docs from this pr
Recommended to remove requestId and time from error body to response headers. This is included to help with debugging/support issues. That is, it is easier for the developer/customer to find this information if it's in the body. IF this is shipping already, then, since it's not part of the contract, it can remain unchanged.
- Note: If the developer is using a client library, then they will get the time & request id in there.
- Please verify the proper RFC for the date-time.
Correct the consumes on line 2616, this should be application/merge-patch+json see: RFC7386
Suggest /fileUploads/configs instead of /fileUploads for the path.
There are a number of "cleanliness" issues that should be addressed before this is release. These can easily be discovered by running the spectral linter that is available in the Azure REST API Style Guide.

Meeting Chat [Meeting Record]()

yang-hai-feng commented 2 years ago

@markweitzel, I have updated the swagger based on review comments, may I get a stamp for merge?