Serializer Registration

.gitignore

@@ -3,3 +3,4 @@
 erl_crash.dump
 /doc
 *.ez
+/cover

CHANGELOG.md

@@ -1,98 +1,109 @@
 # Changelog
 
+## Unreleased
+
+### Backward Incompatible Changes
+
+- There is no longer a default serializer for `application/json`. Please make
+  sure to register a serializer with `OAuth2.Client.put_serializer/3`.
+- Serializers are now registered via `OAuth2.Client.put_serializer/3`.
+  This change allows applications wrapping `oauth2` a way to provide default
+  serializers without requiring the user to manually configure a serializer.
+
 ## v0.9.4 (2018-10-18)
 
 ### Improvements
 
-* Relaxed `hackney` version requirements
+- Relaxed `hackney` version requirements
 
 ## v0.9.3 (2018-08-13)
 
 ### Bug fixes
 
-* Various type specs fixed
+- Various type specs fixed
 
 ## v0.9.2 (2017-11-17)
 
 ### Bug fixes
 
-* Updates the `OAuth2.Client.get_token!` function to handle error `OAuth2.Response` structs.
+- Updates the `OAuth2.Client.get_token!` function to handle error `OAuth2.Response` structs.
 
 ## v0.9.1 (2017-03-10)
 
 ### Improvements
 
-* Fix dialyzer warnings.
-* Update `hackney` to `1.7`
+- Fix dialyzer warnings.
+- Update `hackney` to `1.7`
 
 ### Bug fixes
 
-* De-dupe headers.
+- De-dupe headers.
 
 ## v0.9.0 (2017-02-02)
 
 ### Improvements
 
-* Remove deprecated usage of `Behaviour` and `defcallback`
-* Provides better support for configuring `request_opts` that will be used on
+- Remove deprecated usage of `Behaviour` and `defcallback`
+- Provides better support for configuring `request_opts` that will be used on
   every request. This is useful for configuring SSL options, etc.
-* Provides support for `hackney`s streaming of responses.
-* Better warnings when a serializer isn't properly configured.
+- Provides support for `hackney`s streaming of responses.
+- Better warnings when a serializer isn't properly configured.
 
 ### Backward Incompatible Changes
 
-* Responses with status codes between `400..599` will now return `{:error,
-  %OAuth2.Response{}}` instead of `{:ok, %OAuth2.Response{}}`
-* When using the `!` versions of functions, `{:error, %OAuth2.Response{}}` will
+- Responses with status codes between `400..599` will now return `{:error, %OAuth2.Response{}}` instead of `{:ok, %OAuth2.Response{}}`
+- When using the `!` versions of functions, `{:error, %OAuth2.Response{}}` will
   be converted to an `%OAuth2.Error{}` and raised.
 
 ## v0.8.3 (2017-01-26)
 
-* Fix compile-time warnings for Elixir 1.4
-* Fix dialyzer warnings on `@type params`
-* Fix `content-type` resolving when there are multiple params
-* Return the same refresh token unless a new one is provided
-* Raise an exception when missing serializer configuration
+- Fix compile-time warnings for Elixir 1.4
+- Fix dialyzer warnings on `@type params`
+- Fix `content-type` resolving when there are multiple params
+- Return the same refresh token unless a new one is provided
+- Raise an exception when missing serializer configuration
 
 ## v0.8.2 (2016-11-22)
 
 ### Bug Fixes
 
-* Fixed an issue in handling non-standard `expires` key in access token
+- Fixed an issue in handling non-standard `expires` key in access token
   requests.
 
 ## v0.8.1 (2016-11-18)
 
 ### Improvements
 
-* Added the ability to debug responses from the provider.
+- Added the ability to debug responses from the provider.
 
 ### Bug Fixes
 
-* Fixed regression in handling `text/plain` content-type for tokens in #74
+- Fixed regression in handling `text/plain` content-type for tokens in #74
 
 ## v0.8.0 (2016-10-05)
 
 ### Improvements
 
-* Added `OAuth2.Client.basic_auth/1` convenience function.
+- Added `OAuth2.Client.basic_auth/1` convenience function.
 
 ### Bug Fixes
 
-* Fixed broken `RefreshToken` strategy reported in #66
-* Fixed an issue where checking the `content-type` was defaulting to
+- Fixed broken `RefreshToken` strategy reported in #66
+- Fixed an issue where checking the `content-type` was defaulting to
   `application/json` causing Poison to explode.
 
 ## v0.7.0 (2016-08-16)
 
 ### Improvements
-* Add support for custom serializers based on MIME types.
-* Remove dependency on `HTTPoison` in favor of using `hackney` directly.
-* Remove dependency on `mimetype_parser`.
-* `Poison` is now only a `test` dependency.
+
+- Add support for custom serializers based on MIME types.
+- Remove dependency on `HTTPoison` in favor of using `hackney` directly.
+- Remove dependency on `mimetype_parser`.
+- `Poison` is now only a `test` dependency.
 
 ### Bug Fixes
-* `expires_in` values that are returned as strings are now properly parsed into integers for `expires_at`.
+
+- `expires_in` values that are returned as strings are now properly parsed into integers for `expires_at`.
 
 ### Backward Incompatible Changes
 
@@ -109,74 +120,76 @@ Please consult the [README](https://github.com/scrogson/oauth2/blob/v0.7.0/READM
 
 The following methods have been moved and adjusted so that they take a `OAuth2.Client.t` which contains a token, rather than a token directly:
 
-* `OAuth2.AccessToken.get` -> `OAuth2.Client.get`
-* `OAuth2.AccessToken.get!` -> `OAuth2.Client.get!`
-* `OAuth2.AccessToken.put` -> `OAuth2.Client.put`
-* `OAuth2.AccessToken.put!` -> `OAuth2.Client.put!`
-* `OAuth2.AccessToken.patch` -> `OAuth2.Client.patch`
-* `OAuth2.AccessToken.patch!` -> `OAuth2.Client.patch!`
-* `OAuth2.AccessToken.post` -> `OAuth2.Client.post`
-* `OAuth2.AccessToken.post!` -> `OAuth2.Client.post!`
-* `OAuth2.AccessToken.delete` -> `OAuth2.Client.delete`
-* `OAuth2.AccessToken.delete!` -> `OAuth2.Client.delete!`
-* `OAuth2.AccessToken.refresh` -> `OAuth2.Client.refresh_token`
-* `OAuth2.AccessToken.refresh!` -> `OAuth2.Client.refresh_token!`
+- `OAuth2.AccessToken.get` -> `OAuth2.Client.get`
+- `OAuth2.AccessToken.get!` -> `OAuth2.Client.get!`
+- `OAuth2.AccessToken.put` -> `OAuth2.Client.put`
+- `OAuth2.AccessToken.put!` -> `OAuth2.Client.put!`
+- `OAuth2.AccessToken.patch` -> `OAuth2.Client.patch`
+- `OAuth2.AccessToken.patch!` -> `OAuth2.Client.patch!`
+- `OAuth2.AccessToken.post` -> `OAuth2.Client.post`
+- `OAuth2.AccessToken.post!` -> `OAuth2.Client.post!`
+- `OAuth2.AccessToken.delete` -> `OAuth2.Client.delete`
+- `OAuth2.AccessToken.delete!` -> `OAuth2.Client.delete!`
+- `OAuth2.AccessToken.refresh` -> `OAuth2.Client.refresh_token`
+- `OAuth2.AccessToken.refresh!` -> `OAuth2.Client.refresh_token!`
 
 Additionally, the following methods have been moved to `OAuth2.Request`
 
-* `OAuth2.AccessToken.request` -> `OAuth2.Request.request`
-* `OAuth2.AccessToken.request!` -> `OAuth2.Request.request!`
+- `OAuth2.AccessToken.request` -> `OAuth2.Request.request`
+- `OAuth2.AccessToken.request!` -> `OAuth2.Request.request!`
 
 Diff: https://github.com/scrogson/oauth2/compare/v0.6.0...v0.7.0
 
 ## v0.6.0 (2016-06-24)
 
 ### Improvements
-* Use Poison ~> 2.0
-* Reset client headers after fetching the token
+
+- Use Poison ~> 2.0
+- Reset client headers after fetching the token
 
 ### Bug Fixes
-* Fix up auth code flow to match the RFC
+
+- Fix up auth code flow to match the RFC
 
 Diff: https://github.com/scrogson/oauth2/compare/v0.5.0...v0.6.0
 
 ## v0.5.0 (2015-11-03)
 
 ### Improvements
 
-* You can now request a refresh token with `OAuth2.AccessToken.refresh`. The `!` alternative is also available.
-* Added `Bypass` for improved testability.
-* `Plug` is no longer a direct dependency. It is only included as a test dependency through the `Bypass` library.
-* `OAuth2.AccessToken` now supports `DELETE` requests with `delete` and `delete!`
-* More tests!
+- You can now request a refresh token with `OAuth2.AccessToken.refresh`. The `!` alternative is also available.
+- Added `Bypass` for improved testability.
+- `Plug` is no longer a direct dependency. It is only included as a test dependency through the `Bypass` library.
+- `OAuth2.AccessToken` now supports `DELETE` requests with `delete` and `delete!`
+- More tests!
 
 ### Bug Fixes
 
-* Params are no longer sent in both the body and as a query string for `POST` requests with `OAuth2.Client.get_token`
-* Responses will no longer be parsed automatically if the `content-type` is not supported by this lib. Registering custom parsers is a future goal for this library.
-* Errors are now properly raised when they occur.
+- Params are no longer sent in both the body and as a query string for `POST` requests with `OAuth2.Client.get_token`
+- Responses will no longer be parsed automatically if the `content-type` is not supported by this lib. Registering custom parsers is a future goal for this library.
+- Errors are now properly raised when they occur.
 
 ### Backwards Incompatible Changes
 
-* `OAuth2.new/1` has been removed. Use `OAuth2.Client.new/1` instead.
+- `OAuth2.new/1` has been removed. Use `OAuth2.Client.new/1` instead.
 
 Diff: https://github.com/scrogson/oauth2/compare/v0.4.0...v0.5.0
 
 ## v0.4.0 (2015-10-27)
 
 ### Additions/Improvements
 
-* `OAuth2.AccessToken` now supports: `post`, `post!`, `put`, `put!`, `patch`, and `patch!`.
-* Better documentation
-* Test coverage improved
+- `OAuth2.AccessToken` now supports: `post`, `post!`, `put`, `put!`, `patch`, and `patch!`.
+- Better documentation
+- Test coverage improved
 
 ### Bug fixes
 
-* Empty response bodies are no longer decoded
+- Empty response bodies are no longer decoded
 
 ### Breaking changes
 
-* `OAuth2.AccessToken.get!/4` now returns `OAuth2.Response{}` instead of just the parsed body.
+- `OAuth2.AccessToken.get!/4` now returns `OAuth2.Response{}` instead of just the parsed body.
 
 ### Aknowledgements
 
@@ -190,23 +203,20 @@ Bump `Plug` dependency to `1.0`.
 
 Diff: https://github.com/scrogson/oauth2/compare/v0.2.0...v0.3.0
 
-
 ## v0.2.0 (2015-07-13)
 
 - `:erlang.now` was replaced with `:os.timestamp` for compatibility with Erlang 18
 - You can now pass options to the `HTTPoison` library with `OAuth2.Client.get_token/4` and `OAuth2.Client.get_token!/4`
 
 Diff: https://github.com/scrogson/oauth2/compare/v0.1.1...v0.2.0
 
-
 ## v0.1.1 (2015-04-18)
 
 - Remove compilation warnings.
 - Fix `request_body` function for `ClientCredentials`
 
 Diff: https://github.com/scrogson/oauth2/compare/v0.1.0...v0.1.1
 
-
 ## v0.1.0 (2015-04-14)
 
 This release bring breaking changes and more documentation.
@@ -215,15 +225,13 @@ Please see the [README](https://github.com/scrogson/oauth2/blob/v0.1.0/README.md
 
 Diff: https://github.com/scrogson/oauth2/compare/v0.0.5...v0.1.0
 
-
 ## v0.0.5 (2015-04-11)
 
 - Handles Facebooks `expires` key for Access Tokens.
 - Ensure the token type defaults to 'Bearer' when it is not present.
 
 Diff: https://github.com/scrogson/oauth2/compare/0.0.3...v0.0.5
 
-
 ## v0.0.3 (2015-01-12)
 
 - Relax version requirements for Poison.
@@ -240,4 +248,3 @@ http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.4
 Initial release.
 
 This initial release includes a functional authorization code strategy: http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.1
-

README.md

@@ -25,35 +25,27 @@ end
 ## Configure a serializer
 
 This library can be configured to handle encoding and decoding requests and
-responses automatically.
+responses automatically based on the `accept` and/or `content-type` headers.
 
-If you're using [Poison](https://hex.pm/packages/poison) for JSON in your
-application, this library is already pre-configured to use it for `"application/json"`
-request and response bodies. You will still need to include it as a dependency though.
-
-If you need to handle different MIME types, you can simply configure it like so:
+If you need to handle various MIME types, you can simply register serializers like so:
 
 ```elixir
-# config/config.exs
-config :oauth2,
-  serializers: %{
-    "application/vnd.api+json" => Poison,
-    "application/xml" => MyApp.XmlParser,
-  }
+OAuth2.Client.put_serializer(client, "application/vnd.api+json", Jason)
+OAuth2.Client.put_serializer(client, "application/xml", MyApp.Parsers.XML)
 ```
 
-The `serializers` option is a map where the keys are MIME types and the values
-are modules.
-
 The modules are expected to export `encode!/1` and `decode!/1`.
 
 ```elixir
-defmodule MyApp.XmlParser do
+defmodule MyApp.Parsers.XML do
   def encode!(data), do: # ...
   def decode!(binary), do: # ...
 end
 ```
 
+Please see the documentation for [OAuth2.Serializer](https://hexdocs.pm/oauth2/OAuth2.Serializer.html)
+for more details.
+
 ## Debug mode
 
 Some times its handy to see what's coming back from the response when getting
@@ -158,6 +150,7 @@ defmodule GitHub do
       authorize_url: "https://github.com/login/oauth/authorize",
       token_url: "https://github.com/login/oauth/access_token"
     ])
+    |> OAuth2.Client.put_serializer("application/json", Jason)
   end
 
   def authorize_url! do

config/config.exs

@@ -1,10 +1,9 @@
 use Mix.Config
 
-config :logger, level: :info
+config :logger, level: :debug
 
 config :oauth2,
   client_id: "0bee1126b1a1381d9cab60bcd52349484451808a", # first commit sha of this library
   client_secret: "f715d64092fe81c396ac383e97f8a7eca40e7c89", #second commit sha
   redirect_uri: "http://example.com/auth/callback",
-  serializers: %{"application/json" => Poison},
   request_opts: []

coveralls.json

@@ -0,0 +1,6 @@
+{
+  "skip_files": [
+    "lib/oauth2/strategy.ex",
+    "test/support/test_helpers.ex"
+  ]
+}