api-guidelines
api-guidelines copied to clipboard
microsoft
Operations pattern
I'm confused as to why there is a suggestion that actions/functions are related to performing operations on multiple resources. I don't see any correlation to how many resources are affected.
Actions are implemented via an unsafe data processing resource that where the behaviour does not naturally map to the native HTTP methods and for usability reasons the API designer wants to expose that behaviour as a first class resource. e.g. MarkAsUnread, SendMail
Functions are a way to create read-only resources that are often some kind of convenience composite of other resources.
as we discussed on 07/27/22 we will elevate resource definition for HTTP level to Domain model or OData definition
https://github.com/microsoft/api-guidelines/blob/27aa5a2983d162edf8f4a58360019d4efedbb5dd/graph/patterns/operations.md?plain=1#L24
What is the scenario for a null binding parameter on an action/function?
@PetRich-MSFT honestly i copied it from the wiki but i can imagine that NULL might signify ANY type/collection including recently discussed navigation properties.
I'm confused as to why there is a suggestion that actions/functions are related to performing operations on multiple resources. I don't see any correlation to how many resources are affected.
Actions are implemented via an unsafe data processing resource that where the behaviour does not naturally map to the native HTTP methods and for usability reasons the API designer wants to expose that behaviour as a first class resource. e.g. MarkAsUnread, SendMail
Functions are a way to create read-only resources that are often some kind of convenience composite of other resources.
@darrelmiller The intent is to emphasize that usually operations in opposite to HTTP Methods are applied to a set of resources where the set can't be expressed via a URL. I agree that quantity not a good differentiator, another point is side effects even though a function doesn't produce them. We need to provide clarity on what conditions are right to make behavior the first class citizen. IMO MarkAsUnread is a good candidate for PATCH but sendMail a good candidate for an action because it has side effects. While a function is a read-only resource the function result may not be an addressable resource