search

microsoft / api-guidelines

Microsoft REST API Guidelines
Other
22.69k stars 2.71k forks source link

Add guidelines for polymorphism #433

Closed mikekistler closed 1 year ago

mikekistler commented 1 year ago

This PR adds guidelines for polymorphism and specifically how polymorphism should work in versioned APIs.

JeffreyRichter commented 1 year ago

If I'm following this conversation, then changing a kind to a new value requires the service to delete properties associated with the old kind value

-- Jeffrey

From: Johan Stenberg (MSFT) @.> Sent: Wednesday, March 8, 2023 2:42:31 PM To: microsoft/api-guidelines @.> Cc: Jeffrey Richter @.>; Comment @.> Subject: Re: [microsoft/api-guidelines] Add guidelines for polymorphism (PR #433)

@johanste commented on this pull request.

In azure/Guidelines.mdhttps://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fmicrosoft%2Fapi-guidelines%2Fpull%2F433%23discussion_r1130156558&data=05%7C01%7Cjeffreyr%40microsoft.com%7C28ed9ed46929427b735208db202667d4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C638139121551338317%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=jUcpPeJzXczInzNGGQFduj0XGqNWuVxHNYD2ibit9Eo%3D&reserved=0:

@@ -540,6 +546,18 @@ Below is an example of JSON for a Rectangle and Circle:


Both Rectangle and Circle have common fields: `kind`, `fillColor`, `lineColor`, and `subscription`. A Rectangle also has `x`, `y`, `width`, and `length` while a Circle has `x`, `y`, and `radius`. The `subscription` is a nested polymorphic type. A `free` subscription has no additional fields and a `paid` subscription has `expiration` and `invoice` fields.

+ +:ballot_box_with_check: YOU SHOULD define the kind field of a polymorphic type to be an extensible enum. + + +:warning: YOU SHOULD NOT allow an update (patch) to change the kind field of a polymorphic type.

The question is what you do for fields that were previously set on the resource, but that are not valid on the new kind. This is a sometimes a reason to use PUT rather than PATCH.

The scenarios where this has come up is when changing a data source type etc. (where data source types are pluggable)

— Reply to this email directly, view it on GitHubhttps://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fmicrosoft%2Fapi-guidelines%2Fpull%2F433%23discussion_r1130156558&data=05%7C01%7Cjeffreyr%40microsoft.com%7C28ed9ed46929427b735208db202667d4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C638139121551338317%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=jUcpPeJzXczInzNGGQFduj0XGqNWuVxHNYD2ibit9Eo%3D&reserved=0, or unsubscribehttps://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAARLJP2MQDNXIJWNXBUDYETW3EDNPANCNFSM6AAAAAAUZY2OLI&data=05%7C01%7Cjeffreyr%40microsoft.com%7C28ed9ed46929427b735208db202667d4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C638139121551338317%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=Fii96Hsp7KIUc%2FH8QIiCPo0DS8gzqO8k6KPiVgCS%2FwY%3D&reserved=0. You are receiving this because you commented.Message ID: @.***>

JeffreyRichter commented 1 year ago

Another reason to like our polymorphic type schema proposal.

-- Jeffrey

From: Mike Kistler @.> Sent: Tuesday, March 21, 2023 3:57:26 PM To: microsoft/api-guidelines @.> Cc: Jeffrey Richter @.>; Comment @.> Subject: Re: [microsoft/api-guidelines] Add guidelines for polymorphism (PR #433)

@mikekistler commented on this pull request.

In azure/Guidelines.mdhttps://github.com/microsoft/api-guidelines/pull/433#discussion_r1144068525:

@@ -503,9 +509,9 @@ This indicates to client libraries and customers that values of the enumeration If you can't avoid them, then follow the guideline below.

-:white_check_mark: DO define a kind field indicating the kind of the resource and include any kind-specific fields in the body. +:white_check_mark: DO define a discriminator field indicating the kind of the resource and include any kind-specific fields in the body.

I don't believe it is possible to describe a schema with multiple polymorphic types in OpenAPI. A schema can have at most one discriminator.

— Reply to this email directly, view it on GitHubhttps://github.com/microsoft/api-guidelines/pull/433#discussion_r1144068525, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AARLJP7PI6DN5L5XX3ULWQ3W5IW5NANCNFSM6AAAAAAUZY2OLI. You are receiving this because you commented.Message ID: @.***>