[IoT Central] REST API Review (2022-06-30-preview)

[yang-hai-feng]

Service name IoT Central

Key contact for the review hayang@microsoft.com, Avneet.Singh@microsoft.com,vincenzo.caruso@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 June

A brief description of the material to be reviewed/changed:

1. Add Enrollment Group support
2. Add Scheduled Job Definition support
3. Add Dashboard support
4. Add Unmodeled Device Property support
5. Add Unmodeled Device Command support
6. Update existed Job add optional progress support.
7. Add new route for Device Group List Devices

Swagger PR

[markweitzel]

API Stewardship Board Review: 16-Jun-22

• .../x509/... -- consider making the name plural, e.g. x509Certificates -- this would more clearly imply a collection.
• /enrollmentGorups/{enrollmentGroupId}/x509/primary/verify -- we are leaving this as a POST action instead of our action pattern because it will be consistent with the other paths that are GA'd
• Consider using a path parameter for primary and secondary instead of distinct URLs modeled as an enum
  • Align with DPS (Device Provisioning Service) -- do what they do.
• /scheduledJobs/{scheduledJobId} - Consider "flattening" the polymorphic types into a union with a discriminator. This will greatly simplify the generation of the SDKs that get generated downstream. May not do this b/c of consistency w/already GA'd operations which are already polymorphic (see: ~:32 in the recording)
• Verify that you are declaring the enums as "model as string" in the swagger

Next Steps

• No blockers for preview, assuming the minor updates to the API definition

References

Meeting Chat Meeting Recording