add docs for the ExOvh.Client Behaviour
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145
diff --git a/lib/client.ex b/lib/client.ex
index f235aa3..13417f9 100644
--- a/lib/client.ex
+++ b/lib/client.ex
@@ -1,4 +1,41 @@
defmodule ExOvh.Client do
+ @moduledoc ~S"""
+ Defines a client.
+
+ When used, it expects the :otp_app as an option. The :otp_app should be an
+ application with the configuration settings for ovh and/or hubic.
+
+ ## Example app using the `ExOvh.Client` behaviour
+
+ defmodule TestOs.ExOvh do
+ use ExOvh.Client, otp_app: :test_os
+ end
+
+ ## Example configuration
+
+ config :test_os, TestOs.ExOvh,
+ ovh: %{
+ application_key: "<app_key>",
+ application_secret: "<app_secret>",
+ consumer_key: "<con_key>"
+ },
+ hubic: %{
+ client_id: "<client_id>",
+ client_secret: "<client_secret>",
+ refresh_token: "<refresh_token>",
+ redirect_uri: "<redirect_uri>"
+ }
+
+ Either ovh or hubic can be set to :nil but not both. Both hubic and ovh being absent
+ will result in the supervision tree crashing since there are no application data with
+ which to authenticate requests.
+ For example, if hubic is set to :nil, then the hubic side of the supervision tree
+ will not be started. Then the only functions available will be:
+ TestOs.ExOvh.ovh_request/3
+ TestOs.ExOvh.ovh_prepare_request/3
+
+
+ """
alias ExOvh.Defaults
@@ -74,16 +111,18 @@ defmodule ExOvh.Client do
Returns a tuple `{method, uri, options}` which is the `query_t` tuple.
With the returned query_t, a request can easily be made with
- the `ovh_request` function or [HTTPotion](http://hexdocs.pm/httpotion/HTTPotion.html).
+ [HTTPotion](http://hexdocs.pm/httpotion/HTTPotion.html).
## Example
- Making a request to the custom ovh api:
- query = ExOvh.ovh_prepare_request({:get, "/cdn/webstorage", :nil}, %{})
+ Building a request to the custom ovh api:
+ raw_query = {:get, "<account_name>", %{"format" => "json"}}
+ query = ExOvh.ovh_prepare_request(raw_query, %{})
- Making a request to the openstack compliant ovh cdn webstorage service:
- query = ExOvh.ovh_prepare_request({:get, "<account_name>", %{"format" => "json"}}, %{ openstack: :true, webstorage: "<ovh_service_name>" })
+ Building a request to the openstack compliant ovh cdn webstorage service:
+ raw_query = {:get, "<account_name>", %{"format" => "json"}}
+ query = ExOvh.ovh_prepare_request(raw_query, %{ openstack: :true, webstorage: "<ovh_service_name>" })
"""
@callback ovh_prepare_request(query :: raw_query_t)
:: query_t
@@ -99,10 +138,12 @@ defmodule ExOvh.Client do
## Example
Making a request to the custom ovh api:
- ExOvh.ovh_request({:get, "/cdn/webstorage", :nil}, %{})
+ raw_query = {:get, "<account_name>", %{"format" => "json"}}
+ ExOvh.ovh_request(raw_query, %{})
Making a request to the openstack compliant ovh cdn webstorage service:
- ExOvh.ovh_request({:get, "<account_name>", %{"format" => "json"}}, %{ openstack: :true, webstorage: "<ovh_service_name>" })
+ raw_query = {:get, "<account_name>", %{"format" => "json"}}
+ ExOvh.ovh_request(raw_query, %{ openstack: :true, webstorage: "<ovh_service_name>" })
"""
@callback ovh_request(query :: raw_query_t, opts :: map)
:: {:ok, response_t} | {:error, response_t}
@@ -114,15 +155,45 @@ defmodule ExOvh.Client do
Makes a request to the hubic api.
Returns a map `%{ body: <body>, headers: %{<headers>}, status_code: <code>}`
+
+ Making a request to the custom hubic api:
+ raw_query = {:get, "/scope/scope", :nil}
+ ExOvh.hubic_request(raw_query, %{})
+
+ Making a request to the openstack compliant hubic storage:
+ client = ExOvh
+ account = ExOvh.Hubic.OpenstackApi.Cache.get_account(client)
+ raw_query = {:get, account, %{"format" => "json"}}
+ ExOvh.hubic_request(raw_query, %{ openstack: :true })
"""
@callback hubic_request(query :: raw_query_t, opts :: map)
:: {:ok, response_t} | {:error, response_t}
@doc ~S"""
- Prepares all elements necessary prior to making a request to the hubic api.
+ Prepares all elements necessary for making a request to the hubic api.
Returns a tuple `{method, uri, options}`
+
+ Building a request to the custom hubic api:
+ raw_query = {:get, "/scope/scope", :nil}
+ ExOvh.hubic_prepare_request(raw_query, %{})
+
+ Building a request to the openstack compliant hubic storage
+ with the default client `ExOvh`:
+
+ account = ExOvh.Hubic.OpenstackApi.Cache.get_account()
+ raw_query = {:get, account, %{"format" => "json"}}
+ ExOvh.hubic_prepare_request(raw_query, %{ openstack: :true })
+
+
+ Building a request to the openstack compliant hubic storage with your own
+ client:
+
+ client = MyApp.ExOvh # <-- enter your client here.
+ account = ExOvh.Hubic.OpenstackApi.Cache.get_account(client)
+ raw_query = {:get, account, %{"format" => "json"}}
+ ExOvh.hubic_prepare_request(raw_query, %{ openstack: :true })
"""
@callback hubic_prepare_request(query :: raw_query_t)
:: query_t
diff --git a/lib/hubic/request.ex b/lib/hubic/request.ex
index 4d1b00b..efedf48 100644
--- a/lib/hubic/request.ex
+++ b/lib/hubic/request.ex
@@ -54,7 +54,7 @@ defmodule ExOvh.Hubic.Request do
@spec request(client :: atom, query :: ExOvh.Client.raw_query_t, opts :: map)
:: {:ok, ExOvh.Client.response_t} | {:error, ExOvh.Client.response_t}
def request(client, {method, uri, params} = query, %{ openstack: :true } = opts) do
- Open.request(client, query)
+ Open.request(client, query, opts)
end
def request(client, {method, uri, params} = query, opts) do