Content Negotiation

Content-Type: *
What is it
Sometimes a server application needs to serve different representations of a resource at the same URI. Of course this can be done by hand, manually checking the Accept request header and push the requested form of the content. However, as your app manages more resources and different kind of representations this can be very painful, as you may need to check for Accept-Charset, Accept-Encoding, put some server-side priorities , handle the errors correctly and e.t.c.
There are some web frameworks in Go already struggle to implement a feature like this but they don't do it correctly:
they don't handle accept-charset at all
they don't handle accept-encoding at all
they don't send error status code (406 not acceptable) as RFC proposes and more...
But, fortunately for us, Iris always follows the best practises and the Web standards.
Based on:
​https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation​
​https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept​
​https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Charset​
​https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding​
Implemented on:
​https://github.com/kataras/iris/pull/1316/commits/8ee0de51c593fe0483fbea38117c3c88e065f2ef#diff-15cce7299aae8810bcab9b0bf9a2fdb1​
Introduction
The Context method which is responsible to render specific mime types based on the client's Accept header is the Negotiate one.
Before Negotiate method fired, the handler MUST declare what mime types the server supports to render with safety. We can do that using the Negotiation priorities builder.
The Negotitation priorities builder
The Context method which returns the builder is the Negotiation one.
1
Negotiation() *NegotiationBuilder
Copied!
It returns:
1
type NegotiationBuilder struct {
2
    Accept NegotiationAcceptBuilder
3
    // [other unexproted fields]
4
}
Copied!
The Accept struct field can be used to customize the client's Accept header manually, e.g. when the client does not contain an "application/json" mime type on its Accept header value.
Read more about NegotiationAcceptBuilder.
The NegotitationBuilder has the necessary methods to help you prioritize mime types, charsets and encoding. Read the documentation.
In short, it contains the following methods:
1
// Declare custom mime and optionally content to render.
2
MIME(mime string, content interface{}) *NegotiationBuilder
3
// MIME method helpers:
4
Text(v ...string) *NegotiationBuilder
5
Markdown(v ...[]byte) *NegotiationBuilder
6
Binary(v ...[]byte) *NegotiationBuilder
7
JSON(v ...interface{}) *NegotiationBuilder
8
Problem(v ...interface{}) *NegotiationBuilder
9
JSONP(v ...interface{}) *NegotiationBuilder
10
XML(v ...interface{}) *NegotiationBuilder
11
YAML(v ...interface{}) *NegotiationBuilder
12
Protobuf(v ...interface{}) *NegotiationBuilder
13
MsgPack(v ...interface{}) *NegotiationBuilder
14
Any(v ...interface{}) *NegotiationBuilder
Copied!
1
// Charset
2
Charset(charset ...string) *NegotiationBuilder
Copied!
1
// Encoding (compression)
2
Encoding(encoding ...string) *NegotiationBuilder
3
EncodingGzip() *NegotiationBuilder
Copied!
1
// Clears all the above, resets the builder
2
// if necessary on another handler.
3
Clear() *NegotiationBuilder
Copied!
The Build is called automatically on Negotiate method but it it's exported for a custom implementation of negotiation by the end-developer if ever required.
1
// Build calculates the client's and server's
2
// mime type(s), charset(s) and encoding
3
// and returns the final content type, charset and
4
// encoding that server should render to the client.
5
Build() (contentType, charset, encoding string, content interface{})
Copied!
Usage
The Negotiation is a context method which sets and returns the negotiation builder, so it can be used inside a middleware too.
To declare what mime types server can render and match versus the client's Accept header you can do that:
1
func main() {
2
    users := app.Party("/users")
3
    users.Use(setAcceptTypes)
4
    // [...]
5
}
6
​
7
func setAcceptTypes(ctx iris.Context) {
8
    ctx.Negotiation().JSON().XML().HTML().EncodingGzip()
9
    ctx.Next()
10
}
Copied!
The above will tell the server that we can accept JSON, XML and HTML mime types, optionally encoding by Gzip if the client supports. So far nothing is rendered to the client, learn about the Negotiate method below.
The Negotiate method
The Context.Negotiate method used for serving different representations of a resource at the same URI. It returns context.ErrContentNotSupported when not matched mime types.
1
Negotiate(v interface{}) (int, error)
Copied!
The Context.Negotiate method accepts an interface{} which can be any Go value or a ContentNegotiator or a ContentSelector such as the iris.N structure (see below).
The "v" can be a single iris.N struct value.
The "v" can be any value completes the context.ContentSelector interface.
The "v" can be any value completes the context.ContentNegotiator interface.
The "v" can be any value of struct (JSON, JSONP, XML, YAML, MsgPack, Protobuf) or
string(TEXT, HTML) or []byte(Markdown, Binary) or []byte with any matched mime type.
If the "v" is nil, the Context.Negotitation() builder's content will be used instead, otherwise "v" overrides builder's content (server mime types are still retrieved by its registered, supported, mime list)
Set mime type priorities by [Negotiation().MIME.Text.JSON.XML.HTML...]https://godoc.org/github.com/kataras/iris/context#NegotiationBuilder.JSON).
Set charset priorities by Negotiation().Charset(...).
Set encoding algorithm priorities by Negotiation().Encoding(...).
Modify the accepted by Negotiation().Accept.Override().XML().JSON().Charset(...).Encoding(...).
The iris.N is a struct which can be passed on the Context.Negotiate method. It contains fields which should be filled based on the Context.Negotiation() server side values. If no matched mime then its "Other" field will be sent, which should be a string or []byte. It completes the ContentSelector interface.
1
type N struct {
2
    Text, HTML string
3
    Markdown   []byte
4
    Binary     []byte
5
​
6
    JSON     interface{}
7
    Problem  Problem
8
    JSONP    interface{}
9
    XML      interface{}
10
    YAML     interface{}
11
    Protobuf interface{}
12
    MsgPack  interface{}
13
​
14
    Other []byte // custom content types.
15
}
Copied!
If the given interface{} value is not a type which implements one the above then the Negotiate method will render that based on the request's Accept header value matching the declared priorities.
Note that if the given v interface{} is nil then it will uses the contents declared by the Negotiation builder itself.
Usage
1
func handler(ctx iris.Context) {
2
    // data := [...]
3
    ctx.Negotiation().
4
        JSON(data).
5
        XML(data).
6
        HTML("<h1>Test Name</h1><h2>Age 26</h2>").
7
        EncodingGzip().
8
        Charset("utf-8")
9
​
10
    err := ctx.Negotiate(nil)
11
    // [handle err]
12
}
Copied!
Example
When the client accepts JSON and XML and HTML responses from a specific server's endpoint and the server can render all of them:
1
type testdata struct {
2
    ID   uint64 `json:"id" xml:"ID"`
3
    Name string `json:"name" xml:"Name"`
4
    Age  int    `json:"age" xml:"Age"`
5
}
6
​
7
func main() {
8
    users := app.Party("/users")
9
    users.Use(setAcceptTypes)
10
​
11
    users.Post("/{id:uint64}", handler)
12
    // [...]
13
}
14
​
15
func setAcceptTypes(ctx iris.Context) {
16
    ctx.Negotiation().JSON().XML().HTML().EncodingGzip()
17
    ctx.Next()
18
}
19
​
20
func handler(ctx iris.Context) {
21
    data := testdata{
22
        ID: ctx.Params().GetUint64Default("id", 0),
23
        Name: "Test Name",
24
        Age:  26,
25
    }
26
​
27
    ctx.Negotiate(iris.N{
28
        JSON: data,
29
        XML: data,
30
        HTML: "<h1>Test Name</h1><h2>Age 26</h2>",
31
    })
32
}
Copied!
That's all, read the examples for a comprehensive understanding in practise.