From b3502631c2239b2c56a9cf0d1fa039bf2b5b6c4c Mon Sep 17 00:00:00 2001 From: Maxime Delporte Date: Fri, 24 Oct 2025 14:27:06 +0200 Subject: [PATCH] Creating 'Supported destinations types' and 'Triaging the Decode error' sections. --- README.md | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 67c4f85..19e1f8d 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ A few other important things to mention : ### Enveloping responses -The data of the endpoint /v1/movies/123 is nested under the key "movie", rather than being the top-level JSON object itself. +The data of the endpoint **/v1/movies/123** is nested under the key "movie", rather than being the top-level JSON object itself. Enveloping response data like this isn't strictly necessary, and whether you choose to do so is partly a matter of style and taste. But there are a few tangible benefits : 1. Including a key name (like "movie") at the top-level of the JSON helps make the response more self-documenting. For any humans who see the response out of context, it is a bit easier to understand what the data relates to. @@ -100,6 +100,30 @@ So, if we want to customize how something is encoded, all we need to do is imple An example is available here : **internal/data/runtime.go** +### Supported destinations types + +It's important to mention that certain JSON types can only be successfully decoded to certain Go types. For example, if you have the JSON string **"foo""** it can be decoded into a Go **string**, but trying to decode it into a Go **int** or **bool** will result in an error at runtime. + +The following tables shows the supported target decode destinations for the different JSON types : + +| JSON type | Supported Go types | +|--------------|---------------------------| +| JSON boolean | bool | +| JSON string | string | +| JSON number | int*, uint*, float*, rune | +| JSON array | array, slice | +| JSON object | struct, map | + +### Triaging the Decode error + +The Decode() method could potentially return the following five types of error : + +- **json.SyntaxError** : There is a syntax problem with the JSON being decoded. +- **io.ErrUnexpectedEOF** : There is a syntax problem with the JSON being decoded. +- **json.UnmarshalTypeError** : A JSON value is not appropriate for the destination Go type. +- **json.InvalidUnmarshalError** : The decode destination is not valid (usually because it is not a pointer). This is actually a problem with our application code, not the JSON itself. +- **io.EOF** : The JSON being decoded is empty. + ### System-generated error responses In certain scenarios Go's **http.Server** may still automatically generate and send plain-text HTTP responses. These scenarios include when : @@ -136,7 +160,7 @@ A demonstration will follow when we will use a background goroutine to send welc ### Performance -json.MarshalIndent() takes 65% longer to run and uses around 30% more memory than json.Marshal(), as well as making two more heap allocations. Those figures will change depending on what you're encoding, but they're fairly indicative of the performance impact. +**json.MarshalIndent()** takes 65% longer to run and uses around 30% more memory than **json.Marshal()**, as well as making two more heap allocations. Those figures will change depending on what you're encoding, but they're fairly indicative of the performance impact. For most applications this performance difference simply isn't something that you need to worry about. In real terms, we're talking about a few thousandths of a millisecond - and the improved readability of responses is probably worth this trade-off. -But if your API is operating in a very resource-constrained environment, or needs to manage extremely high levels of traffic, then this is worth being aware of, and you may prefer to stick with using json.Marshal() instead. \ No newline at end of file +But if your API is operating in a very resource-constrained environment, or needs to manage extremely high levels of traffic, then this is worth being aware of, and you may prefer to stick with using **json.Marshal()** instead. \ No newline at end of file