Skip to content

Alternate AIP-193 recommendation #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
saurabhsahni wants to merge 20 commits into
base: main
Choose a base branch
from
Open

Alternate AIP-193 recommendation #45

Changes from 1 commit
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
2ee6e9b
feat: AIP-193
Sep 3, 2020
0908529
Merge branch 'master' into aip-193
Sep 28, 2020
568e0fc
Merge branch 'main' into aip-193
Nov 4, 2021
1519d97
Update aip.md
saurabhsahni Dec 6, 2021
40cff57
Update aip.md
saurabhsahni Dec 7, 2021
1aa3dee
Update aip.md
saurabhsahni Dec 7, 2021
9172c51
adding example good errors
saurabhsahni Dec 7, 2021
6233a69
Adding an errors array
saurabhsahni Dec 14, 2021
421a3fd
Update aip.md
saurabhsahni Jan 11, 2022
2626d27
Updating errors AIP per discussion
saurabhsahni Jan 25, 2022
1c083f9
Clarifying ordinal comparison
saurabhsahni Jan 31, 2022
77ee548
Merge branch 'main' into saurabh-aip-193
saurabhsahni Jan 31, 2022
e66cf0d
clarifying metadata changes can be breaking
saurabhsahni Feb 5, 2022
c499945
Minor tweaks per feedback
saurabhsahni Feb 9, 2022
214fac2
Update aip.md
saurabhsahni Feb 9, 2022
dcc55d8
adding examples
saurabhsahni Feb 15, 2022
3cf2ce2
Update aip.md
saurabhsahni Feb 15, 2022
97eb647
Using message instead of title
saurabhsahni Mar 15, 2022
1de2d49
Update aip.md
saurabhsahni Sep 7, 2022
10c62b6
Update aip.md
saurabhsahni Sep 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions aip/general/0193/aip.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,9 @@ than being expected to constantly add verbose error handling everywhere.

Services **must** clearly distinguish successful responses from error responses
by using appropriate HTTP codes:
- Informational responses **must** use HTTP status codes between 100 and 199.
- Successful responses **must** use HTTP status codes between 200 and 399.
- Informational responses issued on a provisional basis while request processing continues **must** use HTTP status codes between 100 and 199.
- Successful responses **must** use HTTP status codes between 200 and 299.
- HTTP status codes between 300 and 399 **must** be used to indicate further action like URL redirection needs to be taken in order to complete the request.
- Errors indicating a problem with the user's request **must** use HTTP status
codes between 400 and 499.
- Errors indicating a problem with the server's handling of an valid request
Expand All @@ -37,15 +38,17 @@ interface Error {
// A unique identifier that identifies the specific occurrence of the problem. Can be provided to the API owner for debugging purposes.
id?: string
Copy link
Copy Markdown
Author

@saurabhsahni saurabhsahni Dec 6, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

id?: string instead of instance?: string, format: uri-reference

  • More on “instance”:
    • When the "instance" URI is dereferenceable, the problem details object can be fetched from it. It might also return information about the problem occurrence in other formats through use of proactive content negotiation (see [HTTP], Section 12.5.1).
    • When the "instance" URI is not dereferencable, it serves as a unique identifier for the problem occurrence that may be of significance to the server, but is opaque to the client.
  • Practical use cases of returning additional problem details for a specific occurrence through a URL seem limited.
  • To represent a unique identifier for an error, while being compliant with RFC 7807, an alternative name could be “id” (Example usage: Apple, Facebook)

Copy link
Copy Markdown
Author

@saurabhsahni saurabhsahni Jan 11, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alternate options:

  • errorInstanceId
  • traceId
  • requestId
  • occurrenceId

Consensus was to use occurrenceId. id, errorId could be confused as an id unique for this error type instead of the specific occurrence. `


// An array of additional error details. errors?: any[]
// A map of metadata returning additional error details that can be used programmatically
metadata?: dict<string, any>
Copy link
Copy Markdown
Author

@saurabhsahni saurabhsahni Feb 1, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The schema of metadata should be documented and a change in this schema could mean a breaking change.

Copy link
Copy Markdown
Author

@saurabhsahni saurabhsahni Feb 8, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@shwoodard: The schema of metadata should be fixed per type and a change in this schema could mean a breaking change.

}


- The `title` field is intended for consumption by humans, and therefore
**may** change, even within a single version.
- The `code` field is intended to have code written against it, and therefore
**must not** change. Values for this field should be 0-63 characters, and use
only lower-case letters, numbers, and the `-` character.
only lower-case letters, numbers, and the `-` character. These strings should
be comparable using ordinal comparisons.
Copy link
Copy Markdown
Contributor

@gibson042 gibson042 Jan 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this mean? What kind of "ordinal comparisons", and for what purpose?

Copy link
Copy Markdown
Author

@saurabhsahni saurabhsahni Jan 28, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added "ordinal comparison" here per @jskeet's feedback: #45 (comment)

What that would mean here is each a developer should send stable error codes that can always be compared to the exact same numeric character values. For example, an API shouldn't send invalid_auth sometimes and Invalid_Auth other times.

That said, given we're recommending developers to always send lower-case letters here. I'm curious if we need that anymore? @jskeet thoughts?

Comment thread
saurabhsahni marked this conversation as resolved.
Outdated



Expand Down