From nobody Mon Jan 18 14:25:16 2021 Return-Path: X-Original-To: httpapi@ietfa.amsl.com Delivered-To: httpapi@ietfa.amsl.com Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id D89A53A0C2E for ; Mon, 18 Jan 2021 14:25:14 -0800 (PST) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -2.349 X-Spam-Level: X-Spam-Status: No, score=-2.349 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.25, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_BLOCKED=0.001, RCVD_IN_MSPIKE_H2=-0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=microsoft.com Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id LGIgXoCS5VwO for ; Mon, 18 Jan 2021 14:25:12 -0800 (PST) Received: from NAM06-DM3-obe.outbound.protection.outlook.com (mail-eopbgr640113.outbound.protection.outlook.com [40.107.64.113]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id D4C633A0934 for ; Mon, 18 Jan 2021 14:25:12 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=LsIqUHOS+7vforh89NEzW+c2KAsjBRLbMNvf5dLCa+6E6+JQFm/BpVyNVQ4GOTyRvDWwwiJMPf31WVIAo6PIoe47nL/XI7ztVOfij52pQhesraRnmerJcvt3whg/ivd5hexae0JZjV3uhDU7lHXZLPBC3BGJ+aH2ZHswrvH9x8gE4MOiHRG9si9FtrKTtWFM+z5fLxJFLInb9MTAx3Oxe9F2y1v4SVIsWJrs5SwRBIRKszNgwVRyt/ovWrVyCwEnj3KJrI8vpQq0lkDiaXLBOesf8DCzPOeLNTfhLtZnZNM+EmSao/QM9lpzPTcZg7UHdZGj3u0Vk65RJbXOW4rVuQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=RtK0EKN2WTrn45JddJdIc/KbFHkrXRYmasC1HuzIg1E=; b=YEpx+4nFbPW7s/EVYJppVTy3ugEBBCdtLh+t/denXLHJ5VOrbTphQ3GWIMncPTHA30yT89SoRwWdz7KoRFn8XhkJkpV4PClcA2H54QQzRSXTTDVrcBtZjswQehDhs1GrrctnOea608ztx9iw+jYjBElJk/3/+LX74+ble+CqaK4ksVFL7Stpz1AG7YLspRfIkzGF0hRnmjkXUvOFLV0YpIWRJjrFTLUjTybOJNCgYN8092k/bpmpj5WcDifVSzXdL8wB1Epi7TgAbfSuALYu8hYD2wk02h41Apwau4dddA2W3lXBoN++xvRHuxKPfzxhT5d91sDAPDWdO5aQuPj8uQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=microsoft.com; dmarc=pass action=none header.from=microsoft.com; dkim=pass header.d=microsoft.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=RtK0EKN2WTrn45JddJdIc/KbFHkrXRYmasC1HuzIg1E=; b=iIF1agBPYDHGOXc+ySovvvt46YbxTQWN7EWf0/kTqMT1eL91JgkYR8RUtJ5sdUKB/GAeHuGfk6uEqOG2Gm3+/RUd0qtolCclO/+FWNZ74q0PaDII+b9WPY6ghtyM/UH+TqqTgv30mJCVahYYWOjlvoAXL0Ngu2hcy5tMvyTp684= Received: from (2603:10b6:5:1bc::23) by DM6PR00MB0845.namprd00.prod.outlook.com (2603:10b6:5:1bc::23) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3815.0; Mon, 18 Jan 2021 22:25:08 +0000 Received: from DM6PR00MB0845.namprd00.prod.outlook.com ([fe80::6450:8a43:1d66:8d3d]) by DM6PR00MB0845.namprd00.prod.outlook.com ([fe80::6450:8a43:1d66:8d3d%5]) with mapi id 15.20.3815.000; Mon, 18 Jan 2021 22:25:08 +0000 From: Darrel Miller To: "sanjay.dalal@cal.berkeley.edu" , "news@bucksch.org" CC: "httpapi@ietf.org" Thread-Topic: [httpapi] RFC for HTTP API error responses (was: rfc7807 errata or just "more") Thread-Index: AQHW671g/TACg64s7UWvLmCgYJV2FKoton+AgABSH7w= Date: Mon, 18 Jan 2021 22:25:07 +0000 Message-ID: References: <5fc6752d-f3d7-0781-6e3a-1fd99f74a9ad@beonex.com>, In-Reply-To: Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: msip_labels: MSIP_Label_f42aa342-8706-4288-bd11-ebb85995028c_Enabled=True; MSIP_Label_f42aa342-8706-4288-bd11-ebb85995028c_SiteId=72f988bf-86f1-41af-91ab-2d7cd011db47; MSIP_Label_f42aa342-8706-4288-bd11-ebb85995028c_SetDate=2021-01-18T22:25:08.508Z; MSIP_Label_f42aa342-8706-4288-bd11-ebb85995028c_Name=General; MSIP_Label_f42aa342-8706-4288-bd11-ebb85995028c_ContentBits=0; MSIP_Label_f42aa342-8706-4288-bd11-ebb85995028c_Method=Standard; authentication-results: cal.berkeley.edu; dkim=none (message not signed) header.d=none;cal.berkeley.edu; dmarc=none action=none header.from=microsoft.com; x-originating-ip: [74.15.147.35] x-ms-publictraffictype: Email x-ms-office365-filtering-ht: Tenant x-ms-office365-filtering-correlation-id: 44ba2876-beb8-45c3-7fb2-08d8bbffe96b x-ms-traffictypediagnostic: DM6PR00MB0845: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:10000; x-ms-exchange-senderadcheck: 1 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: aUOpwCzGlDSX9ruUGuItZYcLr3hsO96fxXg1UhT6EiUYzN0l1iocwt/jGcq1+vk7KxuhEGBYTEK3OmfuOElGILoMZzhuPJKSC4XMzBJRlD3H7joRxdJKa/PQgyEYntzeCuupSEauDSMEMKTspnpP7PcwRnXz41FEw6x/YfJ9xuNCarOZUgbG8kYGkW5yNMlAq0I5va903WV/9a//yEwhoSUU8zuTK5AsRygJR4838n0iM5vR6H7Wv+2Pcbr1wwX7z6B/gpacCE6AjZHmxVY3t1HEvCKs/rHrtGhrOaJUMh3sUugiHC+BKuPoDednsVt+6rMdaeEpeptLgdbLG4+nSBnS6x9Iqx3iZEsw2eMBeZyThbAxbVO/hzs1bEPTQzEuTo1VSHJM1kYwWMlKc1oS9AQcc2e45DJF+Ce+6jb4bksI7+qh+LaufdxDx5WbF7Ei94tLDmS+I5Y99Ni7cjYfaSpYdqhGQ76e8s/wmYPHDAs0qhcpNwi4GShQbJHsU9TmMsE8ImIiPXbaaENiQKPmEQ== x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:DM6PR00MB0845.namprd00.prod.outlook.com; PTR:; CAT:NONE; SFS:(4636009)(376002)(346002)(366004)(136003)(396003)(39860400002)(71200400001)(66946007)(64756008)(76116006)(66556008)(66476007)(83380400001)(33656002)(66446008)(8990500004)(86362001)(4326008)(82950400001)(5660300002)(52536014)(19627405001)(82960400001)(7696005)(110136005)(316002)(55016002)(2906002)(8936002)(8676002)(478600001)(10290500003)(9686003)(6506007)(26005)(186003)(53546011); DIR:OUT; SFP:1102; x-ms-exchange-antispam-messagedata: =?iso-8859-1?Q?xMEnWyff/sk44CE4XmC2m2O8EP2tur0rnz3/0/w1nuCwm66s/nI2/9fovu?= =?iso-8859-1?Q?k+0TSbbRZrR2dEWs9qnd4bffKX4oIaOHmMPkBhZNF714tsR9aTbvkklVC8?= =?iso-8859-1?Q?qsyi9I6fz1eEl78gTbkPvBHgGFH0gM3tu7wmGNANUmXMpCZeQTVJCvDdsw?= =?iso-8859-1?Q?TBrjKCWYYamf1vfQb4QQxu43/YgB98O7Tzx9LhgUpoc/MeyhNP5ydEPXJM?= =?iso-8859-1?Q?+yICmntBqZR/Zt9ByKdD6Dm4iUJmeLrdpCqg5a0uQHNeloXfmu0NJ6LenC?= =?iso-8859-1?Q?8g8XCA5JmThV64xgEyFNrXmhrWzwapu+0yzJHvsy3YDn8M82x0FwY298Yn?= =?iso-8859-1?Q?3Vk6QXVhYP4DO6iCZBXivW5ITZ0FozR3pAOL7MW+mCoG/E3r5ppXQxPGzW?= =?iso-8859-1?Q?a1aM04NR8sRdOGz6+sYq4MaWlhj30NFlWVMOrslelM2qX3WlBiSgil8yrp?= =?iso-8859-1?Q?Rwox7/P6OePo76xo7YUw5mgi3wUv2UWx+1MED16a9GcyHRWxbbNsuCM9hi?= =?iso-8859-1?Q?s1HxZDW+0H3TSegmQ9dakXJOPdLwGjvIAtOY437ix2bLT2DulPpy0Yagp9?= =?iso-8859-1?Q?lyTXdc7JxHdS3dYEfMD8rcCTaC+5Pozvjqm9GGUl7UVRJK+jV6GiaY+jII?= =?iso-8859-1?Q?teu1TWOUjPIzym+MnorB+NrGK2yYZuIHZP3NdISaUmz59AmGQHDOxqfkiH?= =?iso-8859-1?Q?XKsYjq6lMyXhyj2Env8oHVn7MkmO976OiLbyrb4uPdspk964dVcDgFCJs6?= =?iso-8859-1?Q?HtByiZu858Zrdzq5gEcP7zsIPn9MYW4rSTsqabhpQpdOnT8C93AOeM/NrH?= =?iso-8859-1?Q?JYU30OeT6CI7J6Ik4wYr3PSUSva24JZ2RpH8heAy6ahIzRCi4t1M/2P3o8?= =?iso-8859-1?Q?o2pGRmNTC6GWZU0Yq9C2/lFFyDIhxRPaEJGNUVjI989RqvjMlG/IApBR28?= =?iso-8859-1?Q?dfe2TlerdzSVmooZiPqbclXWG8QVP+zeHSo8uzqJBL9Rl7a+LCrsZ0HsCd?= =?iso-8859-1?Q?Ns42Fc3m6VVYp1mWrDMdccPFihdhMawXOxdsstsU0GgexlRNdU3V5QDIK/?= =?iso-8859-1?Q?jySNqp5vYd9poRwNKigcR2A=3D?= x-ms-exchange-transport-forked: True Content-Type: multipart/alternative; boundary="_000_DM6PR00MB08451F917C6EA61EF2BBD5D1F0A49DM6PR00MB0845namp_" MIME-Version: 1.0 X-OriginatorOrg: microsoft.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: DM6PR00MB0845.namprd00.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 44ba2876-beb8-45c3-7fb2-08d8bbffe96b X-MS-Exchange-CrossTenant-originalarrivaltime: 18 Jan 2021 22:25:07.8981 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 72f988bf-86f1-41af-91ab-2d7cd011db47 X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: 8icNuuKVK55qoa2k5t7+mpvpcQhNra0u6T1CMTsm8DVXztsHHltEl73g7iCkIPUc66KtNwM68BIvUXh7zINxJg== X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM6PR00MB0845 Archived-At: Subject: Re: [httpapi] RFC for HTTP API error responses (was: rfc7807 errata or just "more") X-BeenThere: httpapi@ietf.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Building Blocks for HTTP APIs List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 18 Jan 2021 22:25:15 -0000 --_000_DM6PR00MB08451F917C6EA61EF2BBD5D1F0A49DM6PR00MB0845namp_ Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Ben, Sanjay, From: httpapi on behalf of Sanjay Dalal >I find that error responses - and more generally error handling - is sever= ely lacking in many systems I come across, and it's causing problems during= software development. Huge +1. Lack of it, increases cost of support, affects developer experienc= e. I agree that HTTP errors are often not handled well. However, usually I fi= nd that is because devs over simplify client code to something like: if status =3D=3D 200 then success else throw exception. I find it is this part of RFC 7231 that most developers don't follow, HTTP status codes are extensible. HTTP clients are not required to understand the meaning of all registered status codes, though such understanding is obviously desirable. However, a client MUST understand the class of any status code, as indicated by the first digit, and treat an unrecognized status code as being equivalent to the x00 status code of that class, with the exception that a recipient MUST NOT cache a response with an unrecognized status code. Clients must handle each class of status code, but are not required to hand= le every specific failure condition. Is it your expectation that a client must understand all service-specific m= odes of failure in order to make a request to an HTTP API? On Fri, Jan 15, 2021 at 8:08 PM Ben Bucksch > wrote: I wanted to propose to make a new RFC for nailling down not only the error = responses, but also what information is expected in the response, and the b= ehavioral contract. Errors should be part of the protocol and API contract. Errors are part of the HTTP protocol. That's what 4XX and 5XX status codes= are. Possible errors can be called out in API descriptions like OpenAPI b= ut in my opinion they should never be relied on to be exhaustive by a clien= t. The layered nature of HTTP means that any intermediary could return an = HTTP error response that is not provided by the OpenAPI description. Creating a further refinement of HTTP status codes using service specific p= roblem types can be useful as long as clients can opt-in to processing thos= e new error types. Darrel --_000_DM6PR00MB08451F917C6EA61EF2BBD5D1F0A49DM6PR00MB0845namp_ Content-Type: text/html; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable
Ben, Sanjay,

From: httpapi <httpapi-b= ounces@ietf.org> on behalf of Sanjay Dalal <sanjay.dalal@cal.berkeley= .edu>
>I find that error responses - and more generally error handli= ng - is severely lacking in many systems I come across, and it's causing pr= oblems during software development.

Huge +1. Lack of it, increases cost of support, affects developer= experience.

I agree that HTTP errors are often not handled well.  However, us= ually I find that is because devs over simplify client code to something li= ke: 

   if status =3D=3D 200 then success else throw exception.

I find it is this part of RFC 7231 that most developers don't follow,<= /div> 

   HTTP status codes are ex=
tensible.  HTTP clients are not required to=0A=
   understand the meaning of all registered status codes, though =
such=0A=
   understanding is obviously desirable.  However, a client =
MUST=0A=
   understand the class of any status code, as indicated by the f=
irst=0A=
   digit, and treat an unrecognized status code as being equivale=
nt to=0A=
   the x00 status code of that class, with the exception that a=
=0A=
   recipient MUST NOT cache a response with an unrecognized statu=
s code.
Clients must handle each class of status code, but are not required to= handle every specific failure condition.

Is it your expectation that a client must understand all service-specific m= odes of failure in order to make a request to an HTTP API?

On Fri, Jan 15, 2021 at 8:08 PM Ben= Bucksch <news@bucksch.org> w= rote:
I wanted to propose to make a new RFC for nailling down not only the e= rror responses, but also what information is expected in the response, and = the behavioral contract. Errors should be part of the protocol and API cont= ract.
Errors are part of the HTTP protocol.  That's what 4XX and 5XX st= atus codes are.  Possible errors can be called out in API descriptions= like OpenAPI but in my opinion they should never be relied on to be exhaus= tive by a client.  The layered nature of HTTP means that any intermediary could return an HTTP error response that is no= t provided by the OpenAPI description.

Creating a further refinement of HTTP status codes using service speci= fic problem types can be useful as long as clients can opt-in to processing= those new error types.   

Darrel
--_000_DM6PR00MB08451F917C6EA61EF2BBD5D1F0A49DM6PR00MB0845namp_--