Permalink
Browse files

Added detailed documentation for REST path mapping and RestServiceBas…

…e methods.
  • Loading branch information...
1 parent 6405905 commit 5c442057950e1bf247f778703a7560b47c69bdb3 Tony Chow committed Oct 20, 2011
@@ -6,42 +6,82 @@ namespace ServiceStack.ServiceHost
public interface IServiceRoutes
{
/// <summary>
- /// Register the user-defined restPath for the Service's Request DTO TRequest
+ /// Maps the specified REST path to the specified request DTO.
/// </summary>
- /// <typeparam name="TRequest"></typeparam>
- /// <param name="restPath"></param>
- /// <returns></returns>
+ /// <typeparam name="TRequest">The type of request DTO to map
+ /// the path to.</typeparam>
+ /// <param name="restPath">The path to map the request DTO to.
+ /// See <see cref="RestServiceAttribute.Path">RestServiceAttribute.Path</see>
+ /// for details on the correct format.</param>
+ /// <returns>The same <see cref="IServiceRoutes"/> instance;
+ /// never <see langword="null"/>.</returns>
IServiceRoutes Add<TRequest>(string restPath);
/// <summary>
- /// Register the user-defined restPath, HTTP verbs it applies to (empty == all)
+ /// Maps the specified REST path to the specified request DTO, and
+ /// specifies the HTTP verbs supported by the path.
/// </summary>
- /// <typeparam name="TRequest"></typeparam>
- /// <param name="restPath"></param>
- /// <param name="verbs">comma-delimited verbs e.g. GET,POST,PUT,DELETE</param>
- /// <returns></returns>
+ /// <typeparam name="TRequest">The type of request DTO to map
+ /// the path to.</typeparam>
+ /// <param name="restPath">The path to map the request DTO to.
+ /// See <see cref="RestServiceAttribute.Path">RestServiceAttribute.Path</see>
+ /// for details on the correct format.</param>
+ /// <param name="verbs">
+ /// The comma-delimited list of HTTP verbs supported by the path,
+ /// such as "GET,PUT,DELETE". Specify empty or <see langword="null"/>
+ /// to indicate that all verbs are supported.
+ /// </param>
+ /// <returns>The same <see cref="IServiceRoutes"/> instance;
+ /// never <see langword="null"/>.</returns>
IServiceRoutes Add<TRequest>(string restPath, string verbs);
/// <summary>
- /// Register the user-defined restPath, HTTP verbs it applies to (empty == all) and
- /// the defaultContentType the service should return if not specified by the client
+ /// Maps the specified REST path to the specified request DTO,
+ /// specifies the HTTP verbs supported by the path, and indicates
+ /// the default MIME type of the returned response.
/// </summary>
- /// <typeparam name="TRequest"></typeparam>
- /// <param name="restPath"></param>
- /// <param name="verbs">comma-delimited verbs e.g. GET,POST,PUT,DELETE</param>
- /// <param name="defaultContentType"></param>
- /// <returns></returns>
+ /// <typeparam name="TRequest">The type of request DTO to map
+ /// the path to.</typeparam>
+ /// <param name="restPath">The path to map the request DTO to.
+ /// See <see cref="RestServiceAttribute.Path">RestServiceAttribute.Path</see>
+ /// for details on the correct format.</param>
+ /// <param name="verbs">
+ /// The comma-delimited list of HTTP verbs supported by the path,
+ /// such as "GET,PUT,DELETE".
+ /// </param>
+ /// <param name="defaultContentType">
+ /// The default MIME type in which the response object returned to the client
+ /// is formatted, if formatting hints are not provided by the client.
+ /// Specify <see langword="null"/> or empty to require formatting hints from
+ /// the client.
+ /// </param>
+ /// <returns>The same <see cref="IServiceRoutes"/> instance;
+ /// never <see langword="null"/>.</returns>
IServiceRoutes Add<TRequest>(string restPath, string verbs, string defaultContentType);
- /// <summary>
- /// Register the user-defined restPath, HTTP verbs it applies to (empty == all) and
- /// the defaultContentType the service should return if not specified by the client
- /// </summary>
- /// <param name="requestType"></param>
- /// <param name="restPath"></param>
- /// <param name="verbs">comma-delimited verbs e.g. GET,POST,PUT,DELETE. Pass null to allow all verbs.</param>
- /// <param name="defaultContentType">Pass null to use default.</param>
- /// <returns></returns>
- IServiceRoutes Add(System.Type requestType, string restPath, string verbs, string defaultContentType);
+ /// <summary>
+ /// Maps the specified REST path to the specified request DTO,
+ /// specifies the HTTP verbs supported by the path, and indicates
+ /// the default MIME type of the returned response.
+ /// </summary>
+ /// <param name="requestType">
+ /// The type of request DTO to map the path to.
+ /// </param>
+ /// <param name="restPath">The path to map the request DTO to.
+ /// See <see cref="RestServiceAttribute.Path">RestServiceAttribute.Path</see>
+ /// for details on the correct format.</param>
+ /// <param name="verbs">
+ /// The comma-delimited list of HTTP verbs supported by the path,
+ /// such as "GET,PUT,DELETE".
+ /// </param>
+ /// <param name="defaultContentType">
+ /// The default MIME type in which the response object returned to the client
+ /// is formatted, if formatting hints are not provided by the client.
+ /// Specify <see langword="null"/> or empty to require formatting hints from
+ /// the client.
+ /// </param>
+ /// <returns>The same <see cref="IServiceRoutes"/> instance;
+ /// never <see langword="null"/>.</returns>
+ IServiceRoutes Add(System.Type requestType, string restPath, string verbs, string defaultContentType);
}
}
@@ -3,33 +3,133 @@
namespace ServiceStack.ServiceHost
{
/// <summary>
- /// Used to decorate Request DTO's to associate a RESTful request path mapping with a service
+ /// Used to decorate Request DTO's to associate a RESTful request
+ /// path mapping with a service. Multiple attributes can be applied to
+ /// each request DTO, to map multiple paths to the service.
/// </summary>
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
public class RestServiceAttribute
: Attribute
{
+ /// <summary>
+ /// <para>Initializes an instance of the <see cref="RestServiceAttribute"/> class.</para>
+ /// </summary>
+ /// <param name="path">
+ /// <para>The path template to map to the request. See
+ /// <see cref="Path">RestServiceAttribute.Path</see>
+ /// for details on the correct format.</para>
+ /// </param>
public RestServiceAttribute(string path)
: this(path, null, null)
{
}
+ /// <summary>
+ /// <para>Initializes an instance of the <see cref="RestServiceAttribute"/> class.</para>
+ /// </summary>
+ /// <param name="path">
+ /// <para>The path template to map to the request. See
+ /// <see cref="Path">RestServiceAttribute.Path</see>
+ /// for details on the correct format.</para>
+ /// </param>
+ /// <param name="verbs">A comma-delimited list of HTTP verbs supported by the
+ /// service. If unspecified, all verbs are assumed to be supported.</param>
public RestServiceAttribute(string path, string verbs)
: this(path, verbs, null)
{
}
+ /// <summary>
+ /// <para>Initializes an instance of the <see cref="RestServiceAttribute"/> class.</para>
+ /// </summary>
+ /// <param name="path">
+ /// <para>The path template to map to the request. See
+ /// <see cref="Path">RestServiceAttribute.Path</see>
+ /// for details on the correct format.</para>
+ /// </param>
+ /// <param name="verbs">A comma-delimited list of HTTP verbs supported by the
+ /// service. If unspecified, all verbs are assumed to be supported.</param>
+ /// <param name="defaultContentType">The default MIME type in which the response
+ /// object returned to the client is formatted, if formatting hints are unspecified
+ /// in the URL. Specify <see langword="null"/> or empty to require formatting
+ /// hints from the client.</param>
public RestServiceAttribute(string path, string verbs, string defaultContentType)
{
Path = path;
Verbs = verbs;
DefaultContentType = defaultContentType;
}
+ /// <summary>
+ /// Gets or sets the path template to be mapped to the request.
+ /// </summary>
+ /// <value>
+ /// A <see cref="String"/> value providing the path mapped to
+ /// the request. Never <see langword="null"/>.
+ /// </value>
+ /// <remarks>
+ /// <para>Some examples of valid paths are:</para>
+ ///
+ /// <list>
+ /// <item>"/Inventory"</item>
+ /// <item>"/Inventory/{Category}/{ItemId}"</item>
+ /// <item>"/Inventory/{ItemPath*}"</item>
+ /// </list>
+ ///
+ /// <para>Variables are specified within "{}"
+ /// brackets. Each variable in the path is mapped to the same-named property
+ /// on the request DTO. At runtime, ServiceStack will parse the
+ /// request URL, exact the variable values, instantiate the request DTO,
+ /// and assign the variable values into the corresponding request properties,
+ /// prior to passing the request DTO to the service object for processing.</para>
+ ///
+ /// <para>It is not necessary to specify all request properties as
+ /// variables in the path. For unspecified properties, callers may provide
+ /// values in the query string. For example: the URL
+ /// "http://services/Inventory?Category=Books&ItemId=12345" causes the same
+ /// request DTO to be processed as "http://services/Inventory/Books/12345",
+ /// provided that the paths "/Inventory" (which supports the first URL) and
+ /// "/Inventory/{Category}/{ItemId}" (which supports the second URL)
+ /// are both mapped to the request DTO.</para>
+ ///
+ /// <para>Please note that while it is possible to specify property values
+ /// in the query string, it is generally considered to be less RESTful and
+ /// less desirable than to specify them as variables in the path. Using the
+ /// query string to specify property values may also interfere with HTTP
+ /// caching.</para>
+ ///
+ /// <para>The final variable in the path may contain a "*" suffix
+ /// to grab all subsequent segments in the path portion of the request URL and assign
+ /// them to a single property on the request DTO.
+ /// For example, if the path "/Inventory/{ItemPath*}" is mapped to the request DTO,
+ /// then the request URL "http://services/Inventory/Category/Books/12345" will result
+ /// in a request DTO whose ItemPath property contains "Inventory/Category/Books/12345".
+ /// You may only specify one such variable in the path, and it must be positioned at
+ /// the end of the path.</para>
+ /// </remarks>
public string Path { get; set; }
+ /// <summary>
+ /// Gets or sets a comma-delimited list of HTTP verbs supported by the service, such as
+ /// "GET,PUT,POST,DELETE".
+ /// </summary>
+ /// <value>
+ /// A <see cref="String"/> providing a comma-delimited list of HTTP verbs supported
+ /// by the service, <see langword="null"/> or empty if all verbs are supported.
+ /// </value>
public string Verbs { get; set; }
+ /// <summary>
+ /// Gets or sets the default MIME type in which the response
+ /// object returned to the client is formatted , when format hints
+ /// are not provided in the URI. Some valid examples are such as
+ /// "application/json", or "application/xml".
+ /// </summary>
+ /// <value>
+ /// A <see cref="String"/> providing the default MIME type of the response;
+ /// <see langword="null"/> or empty if formatting hints are required
+ /// from the client.
+ /// </value>
public string DefaultContentType { get; set; }
}
@@ -1,8 +1,14 @@
using System;
+using ServiceStack.Common.Web;
using ServiceStack.ServiceHost;
namespace ServiceStack.ServiceInterface
{
+ /// <summary>
+ /// Base class for services that support HTTP verbs.
+ /// </summary>
+ /// <typeparam name="TRequest">The request class that the descendent class
+ /// is responsible for processing.</typeparam>
public abstract class RestServiceBase<TRequest>
: ServiceBase<TRequest>,
IRestGetService<TRequest>,
@@ -16,6 +22,20 @@ protected override object Run(TRequest request)
throw new NotImplementedException("This base method should be overridden but not called");
}
+ /// <summary>
+ /// The method may overriden by the descendent class to provide support for the
+ /// GET verb on <see cref="TRequest"/> objects.
+ /// </summary>
+ /// <param name="request">The request object containing parameters for the GET
+ /// operation.</param>
+ /// <returns>
+ /// A response object that the client expects, <see langword="null"/> if a response
+ /// object is not applicable, or an <see cref="HttpResult"/> object, to indicate an
+ /// error condition to the client. The <see cref="HttpResult"/> object allows the
+ /// implementation to control the exact HTTP status code returned to the client.
+ /// Any return value other than <see cref="HttpResult"/> causes the HTTP status code
+ /// of 200 to be returned to the client.
+ /// </returns>
public virtual object OnGet(TRequest request)
{
throw new NotImplementedException("This base method should be overridden but not called");
@@ -38,6 +58,20 @@ public object Get(TRequest request)
}
}
+ /// <summary>
+ /// The method may overriden by the descendent class to provide support for the
+ /// PUT verb on <see cref="TRequest"/> objects.
+ /// </summary>
+ /// <param name="request">The request object containing parameters for the PUT
+ /// operation.</param>
+ /// <returns>
+ /// A response object that the client expects, <see langword="null"/> if a response
+ /// object is not applicable, or an <see cref="HttpResult"/> object, to indicate an
+ /// error condition to the client. The <see cref="HttpResult"/> object allows the
+ /// implementation to control the exact HTTP status code returned to the client.
+ /// Any return value other than <see cref="HttpResult"/> causes the HTTP status code
+ /// of 200 to be returned to the client.
+ /// </returns>
public virtual object OnPut(TRequest request)
{
throw new NotImplementedException("This base method should be overridden but not called");
@@ -60,6 +94,20 @@ public object Put(TRequest request)
}
}
+ /// <summary>
+ /// The method may overriden by the descendent class to provide support for the
+ /// POST verb on <see cref="TRequest"/> objects.
+ /// </summary>
+ /// <param name="request">The request object containing parameters for the POST
+ /// operation.</param>
+ /// <returns>
+ /// A response object that the client expects, <see langword="null"/> if a response
+ /// object is not applicable, or an <see cref="HttpResult"/> object, to indicate an
+ /// error condition to the client. The <see cref="HttpResult"/> object allows the
+ /// implementation to control the exact HTTP status code returned to the client.
+ /// Any return value other than <see cref="HttpResult"/> causes the HTTP status code
+ /// of 200 to be returned to the client.
+ /// </returns>
public virtual object OnPost(TRequest request)
{
throw new NotImplementedException("This base method should be overridden but not called");
@@ -82,6 +130,20 @@ public object Post(TRequest request)
}
}
+ /// <summary>
+ /// The method may overriden by the descendent class to provide support for the
+ /// DELETE verb on <see cref="TRequest"/> objects.
+ /// </summary>
+ /// <param name="request">The request object containing parameters for the DELETE
+ /// operation.</param>
+ /// <returns>
+ /// A response object that the client expects, <see langword="null"/> if a response
+ /// object is not applicable, or an <see cref="HttpResult"/> object, to indicate an
+ /// error condition to the client. The <see cref="HttpResult"/> object allows the
+ /// implementation to control the exact HTTP status code returned to the client.
+ /// Any return value other than <see cref="HttpResult"/> causes the HTTP status code
+ /// of 200 to be returned to the client.
+ /// </returns>
public virtual object OnDelete(TRequest request)
{
throw new NotImplementedException("This base method should be overridden but not called");
@@ -104,6 +166,20 @@ public object Delete(TRequest request)
}
}
+ /// <summary>
+ /// The method may overriden by the descendent class to provide support for the
+ /// PATCH verb on <see cref="TRequest"/> objects.
+ /// </summary>
+ /// <param name="request">The request object containing parameters for the PATCH
+ /// operation.</param>
+ /// <returns>
+ /// A response object that the client expects, <see langword="null"/> if a response
+ /// object is not applicable, or an <see cref="HttpResult"/> object, to indicate an
+ /// error condition to the client. The <see cref="HttpResult"/> object allows the
+ /// implementation to control the exact HTTP status code returned to the client.
+ /// Any return value other than <see cref="HttpResult"/> causes the HTTP status code
+ /// of 200 to be returned to the client.
+ /// </returns>
public virtual object OnPatch(TRequest request)
{
throw new NotImplementedException("This base method should be overridden but not called");

0 comments on commit 5c44205

Please sign in to comment.