You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: azure/Guidelines.md
+29-4Lines changed: 29 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -238,7 +238,7 @@ Because of this, required fields can only be introduced in the 1st version of a
238
238
239
239
:white_check_mark:**DO** make fields simple and maintain a shallow hierarchy.
240
240
241
-
:white_check_mark:**DO** use camel case for all JSON field names.
241
+
:white_check_mark:**DO** use camel case for all JSON field names. Do not upper-case acronyms; use camel case.
242
242
243
243
:white_check_mark:**DO** treat JSON field names with case-sensitivity.
244
244
@@ -282,17 +282,42 @@ There are 2 kinds of errors:
282
282
- An error where you expect customer code to gracefully recover at runtime
283
283
- An error indicating a bug in customer code that is unlikely to be recoverable at runtime; the customer must just fix their code
284
284
285
-
:white_check_mark:**DO** return error an `x-ms-error-code` response header with a string value indicating what went wrong.
285
+
:white_check_mark:**DO** return an `x-ms-error-code` response header with a string error code indicating what went wrong.
286
286
287
287
*NOTE: Error code values are part of your API contract (because customer code is likely to do comparisons against them) and cannot change in the future.*
288
288
289
289
:white_check_mark:**DO** carefully craft `x-ms-error-code` string values for errors that are recoverable at runtime.
290
290
291
-
:white_check_mark:**DO** ensure that the top-level `code` field's value is identical to the `x-ms-error-code` header's value (see example body below).
291
+
:white_check_mark:**DO** ensure that the top-level `code` field's value is identical to the `x-ms-error-code` header's value.
292
292
293
293
:white_check_mark:**DO** document the service's error code strings; they are part of the API contract.
294
294
295
-
:white_check_mark:**DO** provide a response body as follows (example):
295
+
:white_check_mark:**DO** provide a response body with the following structure:
296
+
297
+
**ErrorResponse** : Object
298
+
299
+
Property | Type | Required | Description
300
+
-------- | ---- | -------- | -----------
301
+
`error` | ErrorDetail | ✔ | The error object.
302
+
303
+
**ErrorDetail** : Object
304
+
305
+
Property | Type | Required | Description
306
+
-------- | ---- | -------- | -----------
307
+
`code` | String | ✔ | One of a server-defined set of error codes.
308
+
`message` | String | ✔ | A human-readable representation of the error.
309
+
`target` | String | | The target of the error.
310
+
`details` | ErrorDetail[] | | An array of details about specific errors that led to this reported error.
311
+
`innererror` | InnerError | | An object containing more specific information than the current object about the error.
312
+
313
+
**InnerError** : Object
314
+
315
+
Property | Type | Required | Description
316
+
-------- | ---- | -------- | -----------
317
+
`code` | String | | A more specific error code than was provided by the containing error.
318
+
`innererror` | InnerError | | An object containing more specific information than the current object about the error.
0 commit comments