README.md in accept_headers-0.0.6 vs README.md in accept_headers-0.0.7
- old
+ new
@@ -10,21 +10,22 @@
* Strict adherence to [RFC 2616][rfc], specifically [section 14][rfc-sec14]
* Full support for the [Accept][rfc-sec14-1], [Accept-Encoding][rfc-sec14-3],
and [Accept-Language][rfc-sec14-4] HTTP request headers
* `Accept-Charset` is not supported because it's [obsolete](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation#The_Accept-Charset.3A_header)
- * Parser tested against all IANA registered [media types][iana-media-types]
+ * Parser tested against all IANA registered [media types][iana-media-types] and [encodings][iana-encodings]
* A comprehensive [spec suite][spec] that covers many edge cases
This library is optimistic when parsing headers. If a specific media type, encoding, or language can't be parsed, is in an invalid format, or contains invalid characters, it will skip that specific entry when constructing the sorted list. If a `q` value can't be read or is in the wrong format (more than 3 decimal places), it will default it to `0.001` so it still has a chance to match. Lack of an explicit `q` value of course defaults to 1.
[rfc]: http://www.w3.org/Protocols/rfc2616/rfc2616.html
[rfc-sec14]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
[rfc-sec14-1]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
[rfc-sec14-3]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
[rfc-sec14-4]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4
[iana-media-types]: https://www.iana.org/assignments/media-types/media-types.xhtml
+[iana-encodings]: https://www.iana.org/assignments/http-parameters/http-parameters.xml#content-coding
[spec]: http://github.com/kamui/accept_headers/tree/master/spec/
## Installation
Add this line to your application's Gemfile:
@@ -43,24 +44,25 @@
## Usage
### Accept
-`AcceptHeaders::MediaType::Negotiator` is a class that is initialized with an `Accept` header string and will internally store an array of `MediaType`s in descending order according to the spec, which takes into account `q` value, `type`/`subtype` and `params` specificity.
+`AcceptHeaders::MediaType::Negotiator` is a class that is initialized with an `Accept` header string and will internally store an array of `MediaType`s in descending order according to the spec, which takes into account `q` value, `type`/`subtype` and `extensions` specificity.
```ruby
-media_types = AcceptHeaders::MediaType::Negotiator.new("text/*;q=0.3, text/html;q=0.7, text/html;level=1, text/html;level=2;q=0.4, */*;q=0.5")
+accept_header = 'Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, text/html;level=2;q=0.4, */*;q=0.5'
+media_types = AcceptHeaders::MediaType::Negotiator.new(accept_header)
media_types.list
# Returns:
[
- AcceptHeaders::MediaType.new('text', 'html', params: { 'level' => '1' }),
+ AcceptHeaders::MediaType.new('text', 'html', extensions: { 'level' => '1' }),
AcceptHeaders::MediaType.new('text', 'html', q: 0.7),
AcceptHeaders::MediaType.new('*', '*', q: 0.5),
- AcceptHeaders::MediaType.new('text', 'html', q: 0.4, params: { 'level' => '2' }),
+ AcceptHeaders::MediaType.new('text', 'html', q: 0.4, extensions: { 'level' => '2' }),
AcceptHeaders::MediaType.new('text', '*', q: 0.3)
]
```
`#negotiate` takes an array of media range strings supported (by your API or route/controller) and returns a hash where the `supported` key contains the array element matched and the `matched` key containing a `MediaType` that was matched in the `Negotiator`s internal list.
@@ -73,14 +75,24 @@
# Returns:
{
supported: 'text/html',
- matched: AcceptHeaders::MediaType.new('text', 'html', q: 1, params: { 'level' => '1' })
+ matched: AcceptHeaders::MediaType.new('text', 'html', q: 1, extensions: { 'level' => '1' })
}
```
+It returns the matching `MediaType`, so you can see which one matched and also access the `extensions` params. For example, if you wanted to put your API version in the extensions, you could then retrieve the value.
+
+```ruby
+versions_header = 'Accept: application/json;version=2,application/json;version=1;q=0.8'
+media_types = AcceptHeaders::MediaType::Negotiator.new(versions_header)
+
+m = media_types.negotiate('application/json')
+puts m[:match].extensions['version'] # returns '2'
+```
+
`#accept?`:
```ruby
media_types.accept?('text/html') # true
```
@@ -88,11 +100,12 @@
### Accept-Encoding
`AcceptHeader::Encoding::Encoding`:
```ruby
-encodings = AcceptHeaders::Encoding::Negotiator.new("deflate; q=0.5, gzip, compress; q=0.8, identity")
+accept_encoding = 'Accept-Encoding: deflate; q=0.5, gzip, compress; q=0.8, identity'
+encodings = AcceptHeaders::Encoding::Negotiator.new(accept_encoding)
encodings.list
# Returns:
@@ -129,10 +142,11 @@
### Accept-Language
`Accept::Language::Negotiator`:
```ruby
-languages = AcceptHeaders::Language::Negotiator.new("en-*, en-us, *;q=0.8")
+accept_language = 'Accept-Language: en-*, en-us, *;q=0.8'
+languages = AcceptHeaders::Language::Negotiator.new(accept_language)
languages.list
# Returns: