From daeb339ad5823a1afe1dfbef31e406ae1e256ca7 Mon Sep 17 00:00:00 2001 From: Aidan Oldershaw Date: Tue, 14 Apr 2020 14:40:37 -0400 Subject: [PATCH 1/2] RFC #48 Standardize API error messages Signed-off-by: Aidan Oldershaw Co-authored-by: Taylor Silva --- 048-standard-error-messages/proposal.md | 49 +++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 048-standard-error-messages/proposal.md diff --git a/048-standard-error-messages/proposal.md b/048-standard-error-messages/proposal.md new file mode 100644 index 00000000..3a95b2db --- /dev/null +++ b/048-standard-error-messages/proposal.md @@ -0,0 +1,49 @@ +# Summary + +This RFC proposes that the Concourse API standardize on returning human and +machine readable error messages. + +Authors: @taylorsilva @aoldershaw + +# Motivation + +As a consumer of the Concourse API (e.g. `fly`) I want to return a helpful error +messages to my end-user. This proves to be difficult to do because all I can do +is imprecisely reason about why an error occured based on the HTTP status code +returned by the API. + +Example: The API endpoint for getting a pipeline config may return HTTP 404 in +two situations: 1) the config is not found and 2) the pipeline is archived. It's +currently not possible without further introspecition to distinguish between +these two cases at the client level. + + +# Proposal + +When the Concourse API returns an error (4xx and 5xx status codes) it should +return the relevant HTTP status code and set the body to a JSON object of the +following form: + +```json +{ + "type": "MachineReadable", + "message": "human readable" +} +``` + +If further arbitrary details are required any number of extra keys can be added +to the JSON object. + + +# Open Questions + +_Couldn't think of any_ + +# Answered Questions + + + +# New Implications + +Allows for more flexible client-side error handling and more meaningful error +messages. From 5b8fe37a4210c8f89d2077b4128853b3d3d30c35 Mon Sep 17 00:00:00 2001 From: Taylor Silva Date: Tue, 14 Apr 2020 16:55:36 -0400 Subject: [PATCH 2/2] Add open question Signed-off-by: Taylor Silva --- 048-standard-error-messages/proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/048-standard-error-messages/proposal.md b/048-standard-error-messages/proposal.md index 3a95b2db..8f00cb35 100644 --- a/048-standard-error-messages/proposal.md +++ b/048-standard-error-messages/proposal.md @@ -37,7 +37,7 @@ to the JSON object. # Open Questions -_Couldn't think of any_ +* What format should we use? e.g. There's the [jsonAPI spec](https://jsonapi.org/format/#errors) # Answered Questions