diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1060fc1ac..ef2878fcf 100644
--- a/CHANGELOG.md
+++ b/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)
diff --git a/Nexmo.Api/Account.cs b/Nexmo.Api/Account.cs
index 85ed0b017..0c9eeca0e 100644
--- a/Nexmo.Api/Account.cs
+++ b/Nexmo.Api/Account.cs
@@ -72,6 +72,11 @@ public class Number
public string voiceCallbackValue { get; set; }
}
+ ///
+ /// Get current account balance
+ ///
+ /// (Optional) Overridden credentials for only this request
+ /// decimal balance
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;
}
+ ///
+ /// Get Nexmo pricing for the given country
+ ///
+ /// ISO 3166-1 alpha-2 country code
+ /// (Optional) Overridden credentials for only this request
+ /// Pricing data
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;
}
+ ///
+ /// Set account settings
+ ///
+ /// New API secret
+ /// An encoded URI to the webhook endpoint endpoint that handles inbound messages.
+ /// An encoded URI to the webhook endpoint that handles deliver receipts (DLR).
+ /// (Optional) Overridden credentials for only this request
+ /// Updated settings
public static Settings SetSettings(string newsecret = null, string httpMoCallbackurlCom = null, string httpDrCallbackurlCom = null, Credentials creds = null)
{
var parameters = new Dictionary();
@@ -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(response.JsonResponse);
}
+ ///
+ /// Top-up an account that is configured for auto reload.
+ ///
+ /// The ID associated with your original auto-reload transaction.
+ /// (Optional) Overridden credentials for only this request
public static void TopUp(string transaction, Credentials creds = null)
{
ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(Account), "/account/top-up"), new Dictionary
@@ -126,11 +150,22 @@ public static void TopUp(string transaction, Credentials creds = null)
// TODO: return response
}
+ ///
+ /// Retrieve all the phone numbers associated with your account.
+ ///
+ /// (Optional) Overridden credentials for only this request
+ /// All the phone numbers associated with your account.
public static NumbersResponse GetNumbers(Credentials creds = null)
{
return GetNumbers(new NumbersRequest(), creds);
}
+ ///
+ /// Retrieve all the phone numbers associated with your account that match the provided filter
+ ///
+ /// Filter for account numbers list
+ /// (Optional) Overridden credentials for only this request
+ ///
public static NumbersResponse GetNumbers(NumbersRequest request, Credentials creds = null)
{
var json = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(Account), "/account/numbers"), request, creds);
diff --git a/Nexmo.Api/Application.cs b/Nexmo.Api/Application.cs
index 5473d1762..3303ed114 100644
--- a/Nexmo.Api/Application.cs
+++ b/Nexmo.Api/Application.cs
@@ -91,6 +91,7 @@ public class Application
/// Create a new application
///
/// Application request
+ /// (Optional) Overridden credentials for only this request
///
public static ApplicationResponse Create(ApplicationRequest request, Credentials creds = null)
{
@@ -105,6 +106,7 @@ public static ApplicationResponse Create(ApplicationRequest request, Credentials
/// Set the number of items returned on each call to this endpoint. The default is 10 records.
/// Set the offset from the first page. The default value is 0, calls to this endpoint return a page of . For example, set page_index to 3 to retrieve items 31 - 40 when page_size is the default value.
/// Optional id of specific application to retrieve
+ /// (Optional) Overridden credentials for only this request
///
public static List List(int PageSize = 10, int PageIndex = 0, string AppId = "", Credentials creds = null)
{
@@ -136,6 +138,7 @@ public static List List(int PageSize = 10, int PageIndex =
/// Modify a single application
///
/// Application request
+ /// (Optional) Overridden credentials for only this request
///
public static ApplicationResponse Update(ApplicationRequest request, Credentials creds = null)
{
@@ -149,13 +152,14 @@ public static ApplicationResponse Update(ApplicationRequest request, Credentials
///
/// Delete a single application
///
- /// The application id to delete
+ /// The application id to delete
+ /// (Optional) Overridden credentials for only this request
///
- 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;
}
diff --git a/Nexmo.Api/Number.cs b/Nexmo.Api/Number.cs
index c239b0fe0..ccdfe7faf 100644
--- a/Nexmo.Api/Number.cs
+++ b/Nexmo.Api/Number.cs
@@ -81,12 +81,25 @@ public class SearchResults
public IEnumerable numbers { get; set; }
}
+ ///
+ /// Retrieve the list of virtual numbers available for a specific country.
+ ///
+ /// Search filter
+ /// (Optional) Overridden credentials for only this request
+ ///
public static SearchResults Search(SearchRequest request, Credentials creds = null)
{
var json = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(Number), "/number/search/"), request, creds);
return JsonConvert.DeserializeObject(json);
}
+ ///
+ /// Rent a specific virtual number.
+ ///
+ /// ISO 3166-1 alpha-2 country code
+ /// Number to rent
+ /// (Optional) Overridden credentials for only this request
+ ///
public static ResponseBase Buy(string country, string number, Credentials creds = null)
{
var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(Number), "/number/buy"), new Dictionary
@@ -99,6 +112,12 @@ public static ResponseBase Buy(string country, string number, Credentials creds
return JsonConvert.DeserializeObject(response.JsonResponse);
}
+ ///
+ /// Change the webhook endpoints associated with a rented virtual number or associate a virtual number with an Application.
+ ///
+ /// Update request
+ /// (Optional) Overridden credentials for only this request
+ ///
public static ResponseBase Update(NumberUpdateCommand cmd, Credentials creds = null)
{
var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(Number), "/number/update"), cmd, creds);
@@ -106,6 +125,13 @@ public static ResponseBase Update(NumberUpdateCommand cmd, Credentials creds = n
return JsonConvert.DeserializeObject(response.JsonResponse);
}
+ ///
+ /// Cancel your rental of a specific virtual number.
+ ///
+ /// ISO 3166-1 alpha-2 country code
+ /// The number to cancel
+ /// (Optional) Overridden credentials for only this request
+ ///
public static ResponseBase Cancel(string country, string number, Credentials creds = null)
{
var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(Number), "/number/cancel"), new Dictionary
diff --git a/Nexmo.Api/NumberInsight.cs b/Nexmo.Api/NumberInsight.cs
index 0efb305d6..aaa380321 100644
--- a/Nexmo.Api/NumberInsight.cs
+++ b/Nexmo.Api/NumberInsight.cs
@@ -123,6 +123,12 @@ public class NumberInsightResponse
public string roaming_network_code { get; set; }
}
+ ///
+ /// Performs basic semantic checks on given phone number.
+ ///
+ /// NI request
+ /// (Optional) Overridden credentials for only this request
+ ///
public static NumberInsightBasicResponse RequestBasic(NumberInsightBasicRequest request, Credentials creds = null)
{
var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(NumberVerify), "/number/format/json"), request, creds);
@@ -130,6 +136,12 @@ public static NumberInsightBasicResponse RequestBasic(NumberInsightBasicRequest
return JsonConvert.DeserializeObject(response.JsonResponse);
}
+ ///
+ /// Identifies the phone number type and, for mobile phone numbers, the network it is registered with.
+ ///
+ /// NI request
+ /// (Optional) Overridden credentials for only this request
+ ///
public static NumberInsightStandardResponse RequestStandard(NumberInsightBasicRequest request, Credentials creds = null)
{
var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(NumberVerify), "/number/lookup/json"), request, creds);
@@ -137,6 +149,12 @@ public static NumberInsightStandardResponse RequestStandard(NumberInsightBasicRe
return JsonConvert.DeserializeObject(response.JsonResponse);
}
+ ///
+ /// Retrieve validity, roaming, and reachability information about a mobile phone number.
+ ///
+ /// NI advenced request
+ /// (Optional) Overridden credentials for only this request
+ ///
public static NumberInsightRequestResponse Request(NumberInsightRequest request, Credentials creds = null)
{
var response = ApiRequest.DoPostRequest(ApiRequest.GetBaseUriFor(typeof(NumberInsight), "/ni/json"), new Dictionary
@@ -149,6 +167,11 @@ public static NumberInsightRequestResponse Request(NumberInsightRequest request,
return JsonConvert.DeserializeObject(response.JsonResponse);
}
+ ///
+ /// Deserializes a NumberInsight response JSON string
+ ///
+ /// NumberInsight response JSON string
+ ///
public static NumberInsightResponse Response(string json)
{
return JsonConvert.DeserializeObject(json);
diff --git a/Nexmo.Api/NumberVerify.cs b/Nexmo.Api/NumberVerify.cs
index 6d01a5e44..ef823a535 100644
--- a/Nexmo.Api/NumberVerify.cs
+++ b/Nexmo.Api/NumberVerify.cs
@@ -26,6 +26,12 @@ public class VerifyResponse
public string error_text { get; set; }
}
+ ///
+ /// Number Verify: Generate and send a PIN to your user. You use the request_id in the response for the Verify Check.
+ ///
+ /// Verify request
+ /// (Optional) Overridden credentials for only this request
+ ///
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; }
}
+ ///
+ /// Number Verify: Confirm that the PIN you received from your user matches the one sent by Nexmo as a result of your Verify Request.
+ ///
+ /// Check request
+ /// (Optional) Overridden credentials for only this request
+ ///
public static CheckResponse Check(CheckRequest request, Credentials creds = null)
{
var jsonstring = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(NumberVerify), "/verify/check/json"), new Dictionary
@@ -91,6 +103,12 @@ public class CheckObj
public string ip_address { get; set; }
}
+ ///
+ /// Number Verify: Lookup the status of one or more requests.
+ ///
+ /// Search request
+ /// (Optional) Overridden credentials for only this request
+ ///
public static SearchResponse Search(SearchRequest request, Credentials creds = null)
{
var jsonstring = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(NumberVerify), "/verify/search/json"), new Dictionary()
@@ -129,6 +147,12 @@ public class ControlResponse
public string command { get; set; }
}
+ ///
+ /// Number Verify: Control the progress of your Verify Requests.
+ ///
+ /// Control request
+ /// (Optional) Overridden credentials for only this request
+ ///
public static ControlResponse Control(ControlRequest request, Credentials creds = null)
{
var jsonstring = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(NumberVerify), "/verify/control/json"), request, creds);
diff --git a/Nexmo.Api/Request/ApiRequest.cs b/Nexmo.Api/Request/ApiRequest.cs
index da993fc47..69b80da31 100644
--- a/Nexmo.Api/Request/ApiRequest.cs
+++ b/Nexmo.Api/Request/ApiRequest.cs
@@ -13,6 +13,10 @@
namespace Nexmo.Api.Request
{
+ ///
+ /// Responsible for sending all Nexmo API requests that do not make use of Application authentication.
+ /// For application authentication, see VersionedApiRequest.
+ ///
public static class ApiRequest
{
private static StringBuilder BuildQueryString(IDictionary parameters, Credentials creds = null)
@@ -95,6 +99,14 @@ internal static StringBuilder GetQueryStringBuilderFor(object parameters, Creden
return sb;
}
+ ///
+ /// 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.
+ ///
+ /// The URI to GET
+ /// Parameters required by the endpoint (do not include credentials)
+ /// (Optional) Overridden credentials for only this request
+ ///
public static string DoRequest(Uri uri, Dictionary parameters, Credentials creds = null)
{
var sb = BuildQueryString(parameters, creds);
@@ -134,6 +146,15 @@ internal static string DoRequest(Uri uri)
}
}
+ ///
+ /// 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.
+ ///
+ /// HTTP method (POST, PUT, DELETE, etc)
+ /// The URI to communicate with
+ /// Parameters required by the endpoint (do not include credentials)
+ /// (Optional) Overridden credentials for only this request
+ ///
public static NexmoResponse DoRequest(string method, Uri uri, Dictionary parameters, Credentials creds = null)
{
var sb = new StringBuilder();
diff --git a/Nexmo.Api/Request/VersionedApiRequest.cs b/Nexmo.Api/Request/VersionedApiRequest.cs
index 53c724acc..cacac6604 100644
--- a/Nexmo.Api/Request/VersionedApiRequest.cs
+++ b/Nexmo.Api/Request/VersionedApiRequest.cs
@@ -9,6 +9,10 @@
namespace Nexmo.Api.Request
{
+ ///
+ /// Responsible for sending all Nexmo API requests that require Application authentication.
+ /// For older forms of authentication, see ApiRequest.
+ ///
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);
}
+ ///
+ /// 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.
+ ///
+ /// HTTP method (POST, PUT, DELETE, etc)
+ /// The URI to communicate with
+ /// Parameters required by the endpoint (do not include credentials)
+ /// (Optional) Overridden credentials for only this request
+ ///
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
}
}
+ ///
+ /// 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.
+ ///
+ /// The URI to GET
+ /// Parameters required by the endpoint (do not include credentials)
+ /// (Optional) Overridden credentials for only this request
+ ///
public static string DoRequest(Uri uri, object parameters, Credentials creds = null)
{
var sb = GetQueryStringBuilderFor(parameters);
diff --git a/Nexmo.Api/SMS.cs b/Nexmo.Api/SMS.cs
index 20a4e8c8c..01ab78dda 100644
--- a/Nexmo.Api/SMS.cs
+++ b/Nexmo.Api/SMS.cs
@@ -186,6 +186,12 @@ public class SMSInbound
public string udh { get; set; }
}
+ ///
+ /// Send a SMS message.
+ ///
+ /// The SMS message request
+ /// (Optional) Overridden credentials for only this request
+ ///
public static SMSResponse Send(SMSRequest request, Credentials creds = null)
{
if (string.IsNullOrEmpty(request.from))
diff --git a/Nexmo.Api/Search.cs b/Nexmo.Api/Search.cs
index f0a2d9795..5853360a5 100644
--- a/Nexmo.Api/Search.cs
+++ b/Nexmo.Api/Search.cs
@@ -111,6 +111,12 @@ public class SearchRequest
public string to { get; set; }
}
+ ///
+ /// Search for information about a single message that you sent using SMS API.
+ ///
+ /// Nexmo message ID
+ /// (Optional) Overridden credentials for only this request
+ ///
public static Message GetMessage(string id, Credentials creds = null)
{
var json = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(Search), "/search/message"), new Dictionary
@@ -121,12 +127,24 @@ public static Message GetMessage(string id, Credentials creds = null)
return JsonConvert.DeserializeObject(json);
}
+ ///
+ /// Search for information about the messages you sent using SMS API.
+ ///
+ /// Search request with numbers
+ /// (Optional) Overridden credentials for only this request
+ ///
public static Messages GetMessages(SearchRequest request, Credentials creds = null)
{
var json = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(Search), "/search/messages"), request, creds);
return JsonConvert.DeserializeObject>(json);
}
+ ///
+ /// Search for messages that have been rejected by Nexmo. Messages rejected by carrier do not appear.
+ ///
+ /// Search request with numbers
+ /// (Optional) Overridden credentials for only this request
+ ///
public static Messages GetRejections(SearchRequest request, Credentials creds = null)
{
var json = ApiRequest.DoRequest(ApiRequest.GetBaseUriFor(typeof(Search), "/search/rejections"), request, creds);
diff --git a/Nexmo.Api/ShortCode.cs b/Nexmo.Api/ShortCode.cs
index c2385e5ad..a825089ac 100644
--- a/Nexmo.Api/ShortCode.cs
+++ b/Nexmo.Api/ShortCode.cs
@@ -26,6 +26,12 @@ public class AlertRequest
public string type { get; set; }
}
+ ///
+ /// Send a 2FA request.
+ ///
+ /// 2FA request
+ /// (Optional) Overridden credentials for only this request
+ ///
public static SMS.SMSResponse RequestTwoFactorAuth(TwoFactorAuthRequest request, Credentials creds = null)
{
if (!request.pin.HasValue)
@@ -37,6 +43,13 @@ public static SMS.SMSResponse RequestTwoFactorAuth(TwoFactorAuthRequest request,
return JsonConvert.DeserializeObject(json);
}
+ ///
+ /// Send an Event Based Alerts request.
+ ///
+ /// Event Based Alerts request
+ /// Any custom parameters you need for template.
+ /// (Optional) Overridden credentials for only this request
+ ///
public static SMS.SMSResponse RequestAlert(AlertRequest request, Dictionary customValues, Credentials creds = null)
{
var sb = ApiRequest.GetQueryStringBuilderFor(request);