mirror of
https://github.com/zoriya/octokit.net.git
synced 2026-06-05 03:30:34 +00:00
add API doc for ApiConnection
This commit is contained in:
half-ogre
+112
-24
@@ -6,14 +6,27 @@ using Octokit.Internal;
|
||||
|
||||
namespace Octokit
|
||||
{
|
||||
/// <summary>
|
||||
/// A connection for making API requests against URI endpoints.
|
||||
/// Provides type-friendly convenience methods that wrap <see cref="IConnection"/> methods.
|
||||
/// </summary>
|
||||
public class ApiConnection : IApiConnection
|
||||
{
|
||||
readonly IApiPagination _pagination;
|
||||
|
||||
/// <summary>
|
||||
/// Initializes a new instance of the <see cref="ApiConnection"/> class.
|
||||
/// </summary>
|
||||
/// <param name="connection">A connection for making HTTP requests.</param>
|
||||
public ApiConnection(IConnection connection) : this(connection, new ApiPagination())
|
||||
{
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Initializes a new instance of the <see cref="ApiConnection"/> class.
|
||||
/// </summary>
|
||||
/// <param name="connection">A connection for making HTTP requests.</param>
|
||||
/// <param name="pagination">A paginator for paging API responses.</param>
|
||||
protected ApiConnection(IConnection connection, IApiPagination pagination)
|
||||
{
|
||||
Ensure.ArgumentNotNull(connection, "connection");
|
||||
@@ -23,41 +36,85 @@ namespace Octokit
|
||||
_pagination = pagination;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the connection for making HTTP requests.
|
||||
/// </summary>
|
||||
protected IConnection Connection { get; private set; }
|
||||
|
||||
public async Task<TOther> Get<TOther>(Uri endpoint, IDictionary<string, string> parameters)
|
||||
/// <summary>
|
||||
/// Gets the API resource at the specified URI.
|
||||
/// </summary>
|
||||
/// <typeparam name="T">Type of the API resource to get.</typeparam>
|
||||
/// <param name="uri">URI of the API resource to get.</param>
|
||||
/// <param name="parameters">Parameters to add to the API request.</param>
|
||||
/// <returns>The API resource.</returns>
|
||||
/// <exception cref="ApiException">Thrown when an API error occurs.</exception>
|
||||
public async Task<T> Get<T>(Uri uri, IDictionary<string, string> parameters)
|
||||
{
|
||||
Ensure.ArgumentNotNull(endpoint, "endpoint");
|
||||
Ensure.ArgumentNotNull(uri, "uri");
|
||||
|
||||
var response = await Connection.GetAsync<TOther>(endpoint, parameters);
|
||||
var response = await Connection.GetAsync<T>(uri, parameters);
|
||||
return response.BodyAsObject;
|
||||
}
|
||||
|
||||
public async Task<string> GetHtml(Uri endpoint, IDictionary<string, string> parameters)
|
||||
/// <summary>
|
||||
/// Gets the HTML content of the API resource at the specified URI.
|
||||
/// </summary>
|
||||
/// <param name="uri">URI of the API resource to get.</param>
|
||||
/// <param name="parameters">Parameters to add to the API request.</param>
|
||||
/// <returns>The API resource's HTML content.</returns>
|
||||
/// <exception cref="ApiException">Thrown when an API error occurs.</exception>
|
||||
public async Task<string> GetHtml(Uri uri, IDictionary<string, string> parameters)
|
||||
{
|
||||
Ensure.ArgumentNotNull(endpoint, "endpoint");
|
||||
Ensure.ArgumentNotNull(uri, "uri");
|
||||
|
||||
var response = await Connection.GetHtml(endpoint, parameters);
|
||||
var response = await Connection.GetHtml(uri, parameters);
|
||||
return response.Body;
|
||||
}
|
||||
|
||||
public async Task<IReadOnlyList<T>> GetAll<T>(Uri endpoint, IDictionary<string, string> parameters)
|
||||
/// <summary>
|
||||
/// Gets all API resources in the list at the specified URI.
|
||||
/// </summary>
|
||||
/// <typeparam name="T">Type of the API resource in the list.</typeparam>
|
||||
/// <param name="uri">URI of the API resource to get.</param>
|
||||
/// <param name="parameters">Parameters to add to the API request.</param>
|
||||
/// <returns><see cref="IReadOnlyList{T}"/> of the The API resources in the list.</returns>
|
||||
/// <exception cref="ApiException">Thrown when an API error occurs.</exception>
|
||||
public async Task<IReadOnlyList<T>> GetAll<T>(Uri uri, IDictionary<string, string> parameters)
|
||||
{
|
||||
Ensure.ArgumentNotNull(endpoint, "endpoint");
|
||||
Ensure.ArgumentNotNull(uri, "uri");
|
||||
|
||||
return await _pagination.GetAllPages(async () => await GetPage<T>(endpoint, parameters));
|
||||
return await _pagination.GetAllPages(async () => await GetPage<T>(uri, parameters));
|
||||
}
|
||||
|
||||
public async Task<T> Post<T>(Uri endpoint, object data)
|
||||
/// <summary>
|
||||
/// Creates a new API resource in the list at the specified URI.
|
||||
/// </summary>
|
||||
/// <typeparam name="T">The API resource's type.</typeparam>
|
||||
/// <param name="uri">URI of the API resource to get.</param>
|
||||
/// <param name="data">Object that describes the new API resource; this will be serialized and used as the request's body.</param>
|
||||
/// <returns>The created API resource.</returns>
|
||||
/// <exception cref="ApiException">Thrown when an API error occurs.</exception>
|
||||
public async Task<T> Post<T>(Uri uri, object data)
|
||||
{
|
||||
Ensure.ArgumentNotNull(endpoint, "endpoint");
|
||||
Ensure.ArgumentNotNull(uri, "uri");
|
||||
Ensure.ArgumentNotNull(data, "data");
|
||||
|
||||
var response = await Connection.PostAsync<T>(endpoint, data);
|
||||
var response = await Connection.PostAsync<T>(uri, data);
|
||||
|
||||
return response.BodyAsObject;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a new API resource in the list at the specified URI.
|
||||
/// </summary>
|
||||
/// <typeparam name="T">The API resource's type.</typeparam>
|
||||
/// <param name="uri">URI of the API resource to get.</param>
|
||||
/// <param name="rawData">A <see cref="Stream"/> to use as the API request's body.</param>
|
||||
/// <param name="contentType">Content type of the API request.</param>
|
||||
/// <param name="accepts">Accept header to use for the API request.</param>
|
||||
/// <returns>The created API resource.</returns>
|
||||
/// <exception cref="ApiException">Thrown when an API error occurs.</exception>
|
||||
public async Task<T> Post<T>(Uri uri, Stream rawData, string contentType, string accepts)
|
||||
{
|
||||
Ensure.ArgumentNotNull(uri, "uri");
|
||||
@@ -73,42 +130,73 @@ namespace Octokit
|
||||
return response.BodyAsObject;
|
||||
}
|
||||
|
||||
public async Task<T> Put<T>(Uri endpoint, object data)
|
||||
/// <summary>
|
||||
/// Creates or replaces the API resource at the specified URI.
|
||||
/// </summary>
|
||||
/// <typeparam name="T">The API resource's type.</typeparam>
|
||||
/// <param name="uri">URI of the API resource to create or replace.</param>
|
||||
/// <param name="data">Object that describes the API resource; this will be serialized and used as the request's body.</param>
|
||||
/// <returns>The created API resource.</returns>
|
||||
/// <exception cref="ApiException">Thrown when an API error occurs.</exception>
|
||||
public async Task<T> Put<T>(Uri uri, object data)
|
||||
{
|
||||
Ensure.ArgumentNotNull(endpoint, "endpoint");
|
||||
Ensure.ArgumentNotNull(uri, "uri");
|
||||
Ensure.ArgumentNotNull(data, "data");
|
||||
|
||||
var response = await Connection.PutAsync<T>(endpoint, data);
|
||||
var response = await Connection.PutAsync<T>(uri, data);
|
||||
|
||||
return response.BodyAsObject;
|
||||
}
|
||||
|
||||
public async Task<T> Put<T>(Uri endpoint, object data, string twoFactorAuthenticationCode)
|
||||
/// <summary>
|
||||
/// Creates or replaces the API resource at the specified URI.
|
||||
/// </summary>
|
||||
/// <typeparam name="T">The API resource's type.</typeparam>
|
||||
/// <param name="uri">URI of the API resource to create or replace.</param>
|
||||
/// <param name="data">Object that describes the API resource; this will be serialized and used as the request's body.</param>
|
||||
/// <param name="twoFactorAuthenticationCode">The two-factor authentication code in response to the current user's previous challenge.</param>
|
||||
/// <returns>The created API resource.</returns>
|
||||
/// <exception cref="ApiException">Thrown when an API error occurs.</exception>
|
||||
public async Task<T> Put<T>(Uri uri, object data, string twoFactorAuthenticationCode)
|
||||
{
|
||||
Ensure.ArgumentNotNull(endpoint, "endpoint");
|
||||
Ensure.ArgumentNotNull(uri, "endpoint");
|
||||
Ensure.ArgumentNotNull(data, "data");
|
||||
Ensure.ArgumentNotNullOrEmptyString(twoFactorAuthenticationCode, "twoFactorAuthenticationCode");
|
||||
|
||||
var response = await Connection.PutAsync<T>(endpoint, data, twoFactorAuthenticationCode);
|
||||
var response = await Connection.PutAsync<T>(uri, data, twoFactorAuthenticationCode);
|
||||
|
||||
return response.BodyAsObject;
|
||||
}
|
||||
|
||||
public async Task<T> Patch<T>(Uri endpoint, object data)
|
||||
/// <summary>
|
||||
/// Updates the API resource at the specified URI.
|
||||
/// </summary>
|
||||
/// <typeparam name="T">The API resource's type.</typeparam>
|
||||
/// <param name="uri">URI of the API resource to update.</param>
|
||||
/// /// <param name="data">Object that describes the API resource; this will be serialized and used as the request's body.</param>
|
||||
/// <returns>The updated API resource.</returns>
|
||||
/// <exception cref="ApiException">Thrown when an API error occurs.</exception>
|
||||
public async Task<T> Patch<T>(Uri uri, object data)
|
||||
{
|
||||
Ensure.ArgumentNotNull(endpoint, "endpoint");
|
||||
Ensure.ArgumentNotNull(uri, "endpoint");
|
||||
Ensure.ArgumentNotNull(data, "data");
|
||||
|
||||
var response = await Connection.PatchAsync<T>(endpoint, data);
|
||||
var response = await Connection.PatchAsync<T>(uri, data);
|
||||
|
||||
return response.BodyAsObject;
|
||||
}
|
||||
|
||||
public async Task Delete<T>(Uri endpoint)
|
||||
/// <summary>
|
||||
/// Deletes the API object at the specified URI.
|
||||
/// </summary>
|
||||
/// <typeparam name="T">The API resource's type.</typeparam>
|
||||
/// <param name="uri">URI of the API resource to delete.</param>
|
||||
/// <returns>A <see cref="Task"/> for the request's execution.</returns>
|
||||
public async Task Delete<T>(Uri uri)
|
||||
{
|
||||
Ensure.ArgumentNotNull(endpoint, "endpoint");
|
||||
Ensure.ArgumentNotNull(uri, "endpoint");
|
||||
|
||||
await Connection.DeleteAsync<T>(endpoint);
|
||||
await Connection.DeleteAsync<T>(uri);
|
||||
}
|
||||
|
||||
async Task<IReadOnlyPagedCollection<T>> GetPage<T>(Uri endpoint, IDictionary<string, string> parameters)
|
||||
|
||||
@@ -13,15 +13,15 @@ namespace Octokit
|
||||
{
|
||||
[SuppressMessage("Microsoft.Naming", "CA1716:IdentifiersShouldNotMatchKeywords", MessageId = "Get",
|
||||
Justification = "It's fiiiine. It's fine. Trust us.")]
|
||||
Task<T> Get<T>(Uri endpoint, IDictionary<string, string> parameters);
|
||||
Task<string> GetHtml(Uri endpoint, IDictionary<string, string> parameters);
|
||||
Task<IReadOnlyList<T>> GetAll<T>(Uri endpoint, IDictionary<string, string> parameters);
|
||||
Task<T> Post<T>(Uri endpoint, object data);
|
||||
Task<T> Get<T>(Uri uri, IDictionary<string, string> parameters);
|
||||
Task<string> GetHtml(Uri uri, IDictionary<string, string> parameters);
|
||||
Task<IReadOnlyList<T>> GetAll<T>(Uri uri, IDictionary<string, string> parameters);
|
||||
Task<T> Post<T>(Uri uri, object data);
|
||||
Task<T> Post<T>(Uri uri, Stream rawData, string contentType, string accepts);
|
||||
Task<T> Put<T>(Uri endpoint, object data);
|
||||
Task<T> Put<T>(Uri endpoint, object data, string twoFactorAuthenticationCode);
|
||||
Task<T> Patch<T>(Uri endpoint, object data);
|
||||
Task<T> Put<T>(Uri uri, object data);
|
||||
Task<T> Put<T>(Uri uri, object data, string twoFactorAuthenticationCode);
|
||||
Task<T> Patch<T>(Uri uri, object data);
|
||||
[SuppressMessage("Microsoft.Design", "CA1004:GenericMethodsShouldProvideTypeParameter", Justification="Legitimate, but I'm not fixing it just yet.")]
|
||||
Task Delete<T>(Uri endpoint);
|
||||
Task Delete<T>(Uri uri);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user