Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Added detailed documentation for REST path mapping and RestServiceBas…

…e methods.
  • Loading branch information...
commit 5c442057950e1bf247f778703a7560b47c69bdb3 1 parent 6405905
Tony Chow authored
View
92 src/ServiceStack.Interfaces/ServiceHost/IServiceRoutes.cs
@@ -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);
}
}
View
102 src/ServiceStack.Interfaces/ServiceHost/RestServiceAttribute.cs
@@ -3,22 +3,56 @@
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;
@@ -26,10 +60,76 @@ public RestServiceAttribute(string path, string verbs, string defaultContentType
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; }
}
View
76 src/ServiceStack.ServiceInterface/RestServiceBase.cs
@@ -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");
Please sign in to comment.
Something went wrong with that request. Please try again.