Update documentation

CHANGELOG.md

@@ -1,5 +1,9 @@
-# 2.2.0 (2016-12-??)
+# 2.2.0 (2017-01-??)
 
+* Expose internal API request methods to allow custom API calls from library consumers as some new Nexmo API endpoints may not be immediately supported.
+* Allow override of request credentials per API call.
+* Optional configuration and request logging.
+* Support signed requests via security key.
 * Optional API request rate limiting.
 
 # 2.1.2 (2016-12-07)

Nexmo.Api/Account.cs

@@ -72,6 +72,11 @@ public class Number
             public string voiceCallbackValue { get; set; }
         }
 
+        /// <summary>
+        /// Get current account balance
+        /// </summary>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns>decimal balance</returns>
         public static decimal GetBalance(Credentials creds = null)
         {
             var json = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(Account),
@@ -84,6 +89,12 @@ public static decimal GetBalance(Credentials creds = null)
             return obj.value;
         }
 
+        /// <summary>
+        /// Get Nexmo pricing for the given country
+        /// </summary>
+        /// <param name="country">ISO 3166-1 alpha-2 country code</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns>Pricing data</returns>
         public static Pricing GetPricing(string country, Credentials creds = null)
         {
             var json = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(Account),
@@ -98,6 +109,14 @@ public static Pricing GetPricing(string country, Credentials creds = null)
             return obj;
         }
 
+        /// <summary>
+        /// Set account settings
+        /// </summary>
+        /// <param name="newsecret">New API secret</param>
+        /// <param name="httpMoCallbackurlCom">An encoded URI to the webhook endpoint endpoint that handles inbound messages.</param>
+        /// <param name="httpDrCallbackurlCom">An encoded URI to the webhook endpoint that handles deliver receipts (DLR).</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns>Updated settings</returns>
         public static Settings SetSettings(string newsecret = null, string httpMoCallbackurlCom = null, string httpDrCallbackurlCom = null, Credentials creds = null)
         {
             var parameters = new Dictionary<string, string>();
@@ -110,11 +129,16 @@ public static Settings SetSettings(string newsecret = null, string httpMoCallbac
 
             var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(Account), "/account/settings"), parameters, creds);
 
-            // TODO: update secret?
+            // TODO: update secret in config?
 
             return JsonConvert.DeserializeObject<Settings>(response.JsonResponse);
         }
 
+        /// <summary>
+        /// Top-up an account that is configured for auto reload.
+        /// </summary>
+        /// <param name="transaction">The ID associated with your original auto-reload transaction.</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
         public static void TopUp(string transaction, Credentials creds = null)
         {
             ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(Account), "/account/top-up"), new Dictionary<string, string>
@@ -126,11 +150,22 @@ public static void TopUp(string transaction, Credentials creds = null)
             // TODO: return response
         }
 
+        /// <summary>
+        /// Retrieve all the phone numbers associated with your account.
+        /// </summary>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns>All the phone numbers associated with your account.</returns>
         public static NumbersResponse GetNumbers(Credentials creds = null)
         {
             return GetNumbers(new NumbersRequest(), creds);
         }
 
+        /// <summary>
+        /// Retrieve all the phone numbers associated with your account that match the provided filter
+        /// </summary>
+        /// <param name="request">Filter for account numbers list</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static NumbersResponse GetNumbers(NumbersRequest request, Credentials creds = null)
         {
             var json = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(Account), "/account/numbers"), request, creds);

Nexmo.Api/Application.cs

@@ -91,6 +91,7 @@ public class Application
         /// Create a new application
         /// </summary>
         /// <param name="request">Application request</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
         /// <returns></returns>
         public static ApplicationResponse Create(ApplicationRequest request, Credentials creds = null)
         {
@@ -105,6 +106,7 @@ public static ApplicationResponse Create(ApplicationRequest request, Credentials
         /// <param name="PageSize">Set the number of items returned on each call to this endpoint. The default is 10 records.</param>
         /// <param name="PageIndex">Set the offset from the first page. The default value is 0, calls to this endpoint return a page of <page_size>. For example, set page_index to 3 to retrieve items 31 - 40 when page_size is the default value.</param>
         /// <param name="AppId">Optional id of specific application to retrieve</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
         /// <returns></returns>
         public static List<ApplicationResponse> List(int PageSize = 10, int PageIndex = 0, string AppId = "", Credentials creds = null)
         {
@@ -136,6 +138,7 @@ public static List<ApplicationResponse> List(int PageSize = 10, int PageIndex =
         /// Modify a single application
         /// </summary>
         /// <param name="request">Application request</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
         /// <returns></returns>
         public static ApplicationResponse Update(ApplicationRequest request, Credentials creds = null)
         {
@@ -149,13 +152,14 @@ public static ApplicationResponse Update(ApplicationRequest request, Credentials
         /// <summary>
         /// Delete a single application
         /// </summary>
-        /// <param name="AppId">The application id to delete</param>
+        /// <param name="appId">The application id to delete</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
         /// <returns></returns>
-        public static bool Delete(string AppId, Credentials creds = null)
+        public static bool Delete(string appId, Credentials creds = null)
         {
             var sb = ApiRequest.GetQueryStringBuilderFor(new object());
             var response = ApiRequest.DoDeleteRequest(ApiRequest.GetBaseUriFor(typeof(Application),
-                $"/v1/applications/{AppId}?{sb}"), null, creds);
+                $"/v1/applications/{appId}?{sb}"), null, creds);
 
             return response.Status == HttpStatusCode.NoContent;
         }

Nexmo.Api/Number.cs

@@ -81,12 +81,25 @@ public class SearchResults
             public IEnumerable<SearchResult> numbers { get; set; }
         }
 
+        /// <summary>
+        /// Retrieve the list of virtual numbers available for a specific country.
+        /// </summary>
+        /// <param name="request">Search filter</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static SearchResults Search(SearchRequest request, Credentials creds = null)
         {
             var json = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(Number), "/number/search/"), request, creds);
             return JsonConvert.DeserializeObject<SearchResults>(json);
         }
 
+        /// <summary>
+        /// Rent a specific virtual number.
+        /// </summary>
+        /// <param name="country">ISO 3166-1 alpha-2 country code</param>
+        /// <param name="number">Number to rent</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static ResponseBase Buy(string country, string number, Credentials creds = null)
         {
             var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(Number), "/number/buy"), new Dictionary<string, string>
@@ -99,13 +112,26 @@ public static ResponseBase Buy(string country, string number, Credentials creds
             return JsonConvert.DeserializeObject<ResponseBase>(response.JsonResponse);
         }
 
+        /// <summary>
+        /// Change the webhook endpoints associated with a rented virtual number or associate a virtual number with an Application.
+        /// </summary>
+        /// <param name="cmd">Update request</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static ResponseBase Update(NumberUpdateCommand cmd, Credentials creds = null)
         {
             var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(Number), "/number/update"), cmd, creds);
 
             return JsonConvert.DeserializeObject<ResponseBase>(response.JsonResponse);
         }
 
+        /// <summary>
+        /// Cancel your rental of a specific virtual number.
+        /// </summary>
+        /// <param name="country">ISO 3166-1 alpha-2 country code</param>
+        /// <param name="number">The number to cancel</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static ResponseBase Cancel(string country, string number, Credentials creds = null)
         {
             var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(Number), "/number/cancel"), new Dictionary<string, string>

Nexmo.Api/NumberInsight.cs

@@ -123,20 +123,38 @@ public class NumberInsightResponse
             public string roaming_network_code { get; set; }
         }
 
+        /// <summary>
+        /// Performs basic semantic checks on given phone number.
+        /// </summary>
+        /// <param name="request">NI request</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static NumberInsightBasicResponse RequestBasic(NumberInsightBasicRequest request, Credentials creds = null)
         {
             var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(NumberVerify), "/number/format/json"), request, creds);
 
             return JsonConvert.DeserializeObject<NumberInsightBasicResponse>(response.JsonResponse);
         }
 
+        /// <summary>
+        /// Identifies the phone number type and, for mobile phone numbers, the network it is registered with.
+        /// </summary>
+        /// <param name="request">NI request</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static NumberInsightStandardResponse RequestStandard(NumberInsightBasicRequest request, Credentials creds = null)
         {
             var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(NumberVerify), "/number/lookup/json"), request, creds);
 
             return JsonConvert.DeserializeObject<NumberInsightStandardResponse>(response.JsonResponse);
         }
 
+        /// <summary>
+        /// Retrieve validity, roaming, and reachability information about a mobile phone number.
+        /// </summary>
+        /// <param name="request">NI advenced request</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static NumberInsightRequestResponse Request(NumberInsightRequest request, Credentials creds = null)
         {
             var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(NumberInsight), "/ni/json"), new Dictionary<string, string>
@@ -149,6 +167,11 @@ public static NumberInsightRequestResponse Request(NumberInsightRequest request,
             return JsonConvert.DeserializeObject<NumberInsightRequestResponse>(response.JsonResponse);
         }
 
+        /// <summary>
+        /// Deserializes a NumberInsight response JSON string
+        /// </summary>
+        /// <param name="json">NumberInsight response JSON string</param>
+        /// <returns></returns>
         public static NumberInsightResponse Response(string json)
         {
             return JsonConvert.DeserializeObject<NumberInsightResponse>(json);

Nexmo.Api/NumberVerify.cs

@@ -26,6 +26,12 @@ public class VerifyResponse
             public string error_text { get; set; }
         }
 
+        /// <summary>
+        /// Number Verify: Generate and send a PIN to your user. You use the request_id in the response for the Verify Check.
+        /// </summary>
+        /// <param name="request">Verify request</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static VerifyResponse Verify(VerifyRequest request, Credentials creds = null)
         {
             var jsonstring = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(NumberVerify), "/verify/json"), request, creds);
@@ -48,6 +54,12 @@ public class CheckResponse
             public string error_text { get; set; }
         }
 
+        /// <summary>
+        /// Number Verify: Confirm that the PIN you received from your user matches the one sent by Nexmo as a result of your Verify Request.
+        /// </summary>
+        /// <param name="request">Check request</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static CheckResponse Check(CheckRequest request, Credentials creds = null)
         {
             var jsonstring = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(NumberVerify), "/verify/check/json"), new Dictionary<string, string>
@@ -91,6 +103,12 @@ public class CheckObj
             public string ip_address { get; set; }
         }
 
+        /// <summary>
+        /// Number Verify: Lookup the status of one or more requests.
+        /// </summary>
+        /// <param name="request">Search request</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static SearchResponse Search(SearchRequest request, Credentials creds = null)
         {
             var jsonstring = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(NumberVerify), "/verify/search/json"), new Dictionary<string, string>()
@@ -129,6 +147,12 @@ public class ControlResponse
             public string command { get; set; }
         }
 
+        /// <summary>
+        /// Number Verify: Control the progress of your Verify Requests.
+        /// </summary>
+        /// <param name="request">Control request</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static ControlResponse Control(ControlRequest request, Credentials creds = null)
         {
             var jsonstring = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(NumberVerify), "/verify/control/json"), request, creds);

Nexmo.Api/Request/ApiRequest.cs

@@ -13,6 +13,10 @@
 
 namespace Nexmo.Api.Request
 {
+    /// <summary>
+    /// Responsible for sending all Nexmo API requests that do not make use of Application authentication.
+    /// For application authentication, see VersionedApiRequest.
+    /// </summary>
     public static class ApiRequest
     {
         private static StringBuilder BuildQueryString(IDictionary<string, string> parameters, Credentials creds = null)
@@ -95,6 +99,14 @@ internal static StringBuilder GetQueryStringBuilderFor(object parameters, Creden
             return sb;
         }
 
+        /// <summary>
+        /// Send a GET request to the Nexmo API.
+        /// Do not include credentials in the parameters object. If you need to override credentials, use the optional Credentials parameter.
+        /// </summary>
+        /// <param name="uri">The URI to GET</param>
+        /// <param name="parameters">Parameters required by the endpoint (do not include credentials)</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static string DoRequest(Uri uri, Dictionary<string, string> parameters, Credentials creds = null)
         {
             var sb = BuildQueryString(parameters, creds);
@@ -134,6 +146,15 @@ internal static string DoRequest(Uri uri)
             }
         }
 
+        /// <summary>
+        /// Send a request to the Nexmo API.
+        /// Do not include credentials in the parameters object. If you need to override credentials, use the optional Credentials parameter.
+        /// </summary>
+        /// <param name="method">HTTP method (POST, PUT, DELETE, etc)</param>
+        /// <param name="uri">The URI to communicate with</param>
+        /// <param name="parameters">Parameters required by the endpoint (do not include credentials)</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static NexmoResponse DoRequest(string method, Uri uri, Dictionary<string, string> parameters, Credentials creds = null)
         {
             var sb = new StringBuilder();

Nexmo.Api/Request/VersionedApiRequest.cs

@@ -9,6 +9,10 @@
 
 namespace Nexmo.Api.Request
 {
+    /// <summary>
+    /// Responsible for sending all Nexmo API requests that require Application authentication.
+    /// For older forms of authentication, see ApiRequest.
+    /// </summary>
     public static class VersionedApiRequest
     {
         private static StringBuilder GetQueryStringBuilderFor(object parameters)
@@ -97,6 +101,15 @@ internal static void SetUserAgent(ref HttpRequestMessage request)
             request.Headers.UserAgent.ParseAdd(_userAgent);
         }
 
+        /// <summary>
+        /// Send a request to the versioned Nexmo API.
+        /// Do not include credentials in the parameters object. If you need to override credentials, use the optional Credentials parameter.
+        /// </summary>
+        /// <param name="method">HTTP method (POST, PUT, DELETE, etc)</param>
+        /// <param name="uri">The URI to communicate with</param>
+        /// <param name="payload">Parameters required by the endpoint (do not include credentials)</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static NexmoResponse DoRequest(string method, Uri uri, object payload, Credentials creds = null)
         {
             var appId = creds?.ApplicationId ?? Configuration.Instance.Settings["appSettings:Nexmo.Application.Id"];
@@ -147,6 +160,14 @@ public static NexmoResponse DoRequest(string method, Uri uri, object payload, Cr
             }
         }
 
+        /// <summary>
+        /// Send a GET request to the versioned Nexmo API.
+        /// Do not include credentials in the parameters object. If you need to override credentials, use the optional Credentials parameter.
+        /// </summary>
+        /// <param name="uri">The URI to GET</param>
+        /// <param name="parameters">Parameters required by the endpoint (do not include credentials)</param>
+        /// <param name="creds">(Optional) Overridden credentials for only this request</param>
+        /// <returns></returns>
         public static string DoRequest(Uri uri, object parameters, Credentials creds = null)
         {
             var sb = GetQueryStringBuilderFor(parameters);