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);