search

microsoft / api-guidelines

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

Which one to choose for error response RFC7807 specifications or Json API specifications or Microsoft's custom specifications #206

Open BlackRider97 opened 4 years ago

BlackRider97 commented 4 years ago

.Net Core 3.0+ framework by default returns Problem details and following RFC7807 specifications to return model validation error or internal server error. Net core 3.0+ framework also expects us to write own CustomProblemDetailsFactory to extend these HTTP errors based on business logic exceptions. Looking at latest Net core framework, it seems like Microsoft is putting efforts into RFC7807 error specifications. Azure ARM team is following their own error specifications which is some where close to Json-API specifications Now question is which specifications we should follow where we are exposing bunch of external user facing APIs just like blob storage, cosmos db etc. services within Azure. We are building a new user facing Azure managed service. We also needed our own RP service so that ARM can call our APIs and ARM team has own specifications. Should we use same ARM error specifications for user facing APIs (data-plane) for consistency or keep separate models ?

garethj-msft commented 3 years ago

I'll answer with a meta-response if you don't mind. By default if you're a Microsoft team you should follow the top level Microsoft guideline and return the error specification it provides.

If you are an Azure team, then you should layer on top of that the Azure guidance and return whatever that provides, if it overrides the company-wide guidance.

If you are a Microsoft Graph team, then you should layer on top of that the Microsoft Graph guidance (coming to a repo near you soon) and return whatever that provides, if it overrides the company-wide guidance.

Sounds like you are an Azure team.

If you are not a Microsoft team, but are taking these guidelines in whole or in part to help with your own guidelines, I would tend to look favorably at RFC7807. I am sure we would have snapped to it had it been available at the time we were doing the design of our own error. At this point, the breaking change to APIs necessary for Microsoft to adopt it, or the inconsistency for us to adopt it for new services only is a cost that outweighs the benefits it brings.