diff --git a/README.md b/README.md index fe49df2..764b5d8 100644 --- a/README.md +++ b/README.md @@ -42,4 +42,33 @@ There are two comon approaches to doing this : 1. By prefixing all URLs with your API version, like **/v1/healthcheck** or **/v2/healthcheck** 2. By using custom **Accept** and **Content-Type** headers on requests and responses to convey the API version, like **Accept: application/vnd.greenlight-v1** -From an HTTP semantics point of view, using headers to convey the API version is the 'purer' approach. But from a user-experience point of view, using a URL prefix is arguably better. It makes it possible for developers to see which version of the API is being used at a glance, and it also means that the API can still be explored using a regular web browser (which is harder if custom headers are required). \ No newline at end of file +From an HTTP semantics point of view, using headers to convey the API version is the 'purer' approach. But from a user-experience point of view, using a URL prefix is arguably better. It makes it possible for developers to see which version of the API is being used at a glance, and it also means that the API can still be explored using a regular web browser (which is harder if custom headers are required). + +## Additional Information + +### How different Go Types are encoded + +The following table summarizes how different Go types are mapped to JSON data types during encoding : + +| Go type | JSON type | +|---------------------------------------------------|----------------------------| +| bool | JSON boolean | +| string | JSON string | +| int*, uint*, float*, rune | JSON number | +| array, slice | JSON array | +| struct, map | JSON object | +| nil pointers, interface values, slices, maps, etc | JSON null | +| chan, func, complex* | Not supported | +| time.Time | RFC3339-format JSON string | +| []byte | Base64-encoded JSON string | +| +The last two of these are special cases which deserve a bit more explanation : + +- Go **time.Time** values (which are actually a struct behind the scenes) will be encoded as a JSON string in RFC 3339 format like **"2020-11-08T06:27:59+01:00"**, rather than as a JSON object. +- A **[]byte** slice will be encoded as a base64-encoded JSON string, rather than as a JSON array. So, for example, a byte slice of **[]byte{'h','e','l','l','o'}** would appear as **"aGVsbG8="** in the JSON output. The base64 encoding uses padding and the standard character set. + +A few other important things to mention : + +- Encoding of nested objects is supported. So, for example, if you have a slice of structs in Go that will encode to an *array of objects* in JSON. +- Channels, functions and **complex** number types cannot be encoded. If you try to do so, you'll get a **json.UnsupportedTypeError** error at runtime. +- Any pointer values will encode as *the value pointed to*. \ No newline at end of file