[IoT Central] REST API Review 1.2-preview

[yang-hai-feng]

Service name IoT Central

Key contact for the review hayang@microsoft.com, Avneet.Singh@microsoft.com

Whether this is a new or existing API Existing API

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

A brief description of the material to be reviewed/changed

• Add Device Group Create, Update, Remove, Get support.
• Update Device Group Contract with filter, description, etag fields.
• Update Existed Device Group List API to support $filter, $orderby, $top.
• Add new Device Template Migration Job Type in exsited Jobs API.

Swagger PR

[scgbear]

API Stewardship Board Review Meeting 30-March-22

Discussion / Notes

DeviceGroup

• New fields being added are marked as required == breaking change when added to a create request model. Service is using json patch so the required flag shouldn't be an issue. If changed to a json merge patch, there will be an issue that needs to be worked out.
• Version 1 is using UX, and the UX has these fields as required. New version is adding them and making them required in the OpenAPI doc.
• Using json patch instead of json merge patch. Issue is json patch is not idempotent. Service team is doing to maintain consistency with Digital Twins: RE Brian Crawford.
• $ being used on $filter, $top and $orderBy: General advice is to remove them, again being added for consistency. Will address before going GA with the new service.
• Not using odata, should add help info on the query language.

Jobs

• Data field changed: Job Type discriminator allows the data field to be expanded without it being a breaking changes.
• Down converting models that have been changed from one version to another. Specifically a new required field added to a new version. Definitly a breaking change. Can be accomplished by having different endpoints, could use APIM to route to the correct endpoints. Service team to work with the Breaking Change board to work through the mechanics when the change is introduced.
• CapabilityJobData: value field has no swagger type

General

• Review model names to be less verbose. Not a breaking change, but should be reviewed before going GA.
• Default responses missing on all of the operations. Should document the error response structure.

Actions

• Follow up with Brian Crawford on the use of json patch vs json merge patch.
• Should add help info on the query language being used.
• Service team to work with the Breaking Change board to work through the breaking changes that will be introduced with the model changes coming in later previews.
• CapabilityJobData: add swagger type to value field.
• Default responses missing on all of the operations. Should document the error response structure.

References

Meeting Chat Meeting Recording

Helpful Documentation

• Azure API REST Documentation
• Considerations for Service Design
• REST API Guidelines
• OpenAPI Style Guidelines
• Breaking Changes

_{Note: The Teams channel is internal MS.}