Content negotiation - iris - Euphoria Laxis: Gitea Server

mirror of https://github.com/kataras/iris.git synced 2025-01-23 02:31:04 +01:00

Table of Contents

Example
Documentation

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:

Implemented on:

8ee0de51c5 (diff-15cce7299aae8810bcab9b0bf9a2fdb1)

Example

type testdata struct {
	Name string `json:"name" xml:"Name"`
	Age  int    `json:"age" xml:"Age"`
}

Render a resource with "gzip" encoding algorithm as application/json or text/xml or application/xml

when client's accept header contains one of them
or JSON (the first declared) if accept is empty,
and when client's accept-encoding header contains "gzip" or it's empty.

app.Get("/resource", func(ctx iris.Context) {
	data := testdata{
		Name: "test name",
		Age:  26,
	}

        ctx.Negotiation().JSON().XML().EncodingGzip()

	_, err := ctx.Negotiate(data)
	if err != nil {
		ctx.Writef("%v", err)
	}
})

OR define them in a middleware and call Negotiate with nil in the final handler.

ctx.Negotiation().JSON(data).XML(data).Any("content for */*")
ctx.Negotiate(nil)

app.Get("/resource2", func(ctx iris.Context) {
	jsonAndXML := testdata{
		Name: "test name",
		Age:  26,
	}

	ctx.Negotiation().
		JSON(jsonAndXML).
		XML(jsonAndXML).
		HTML("<h1>Test Name</h1><h2>Age 26</h2>")

	ctx.Negotiate(nil)
})

Read the full example.

Documentation

The Context.Negotiation method creates once and returns the negotiation builder to build server-side available prioritized content for specific content type(s), charset(s) and encoding algorithm(s).

Context.Negotiation() *context.NegotiationBuilder

The Context.Negotiate method used for serving different representations of a resource at the same URI. It returns context.ErrContentNotSupported when not matched mime type(s).

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) 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....
Set charset priorities by Negotiation().Charset(...).
Set encoding algorithm priorities by Negotiation().Encoding(...).
Modify the accepted by Negotiation().Accept./Override()/.XML().JSON().Charset(...).Encoding(...)....

Context.Negotiate(v interface{}) (int, error)

What is Iris
📌Getting Started
- Installing Iris
- Quick start
Host
- Automatic Public Domain with TLS
Configuration
Routing
- Path Parameter Types
- Reverse Lookups
- Middleware
- Handle HTTP errors
- Subdomains
- Wrap the Router
- Override Context
- Context Methods
HTTP Method Override
API Versioning
Content Negotiation
Response Recorder
HTTP Referrer
Request Authentication
URL Query Parameters
Forms
Model Validation
Cache
View
Cookies
Sessions
- Database
- Flash Messages
Websockets
Dependency Injection
MVC
gRPC
Sitemap
Localization
Testing

🤓Resources