Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Added detailed documentation for REST path mapping and RestServiceBas…

…e methods.
  • Loading branch information...
commit bad04c6bcd2fdb08fad8b9d85a388303500dc445 1 parent 6405905
authored October 20, 2011
92  src/ServiceStack.Interfaces/ServiceHost/IServiceRoutes.cs
@@ -6,42 +6,82 @@ namespace ServiceStack.ServiceHost
6 6
 	public interface IServiceRoutes
7 7
 	{
8 8
 		/// <summary>
9  
-		/// Register the user-defined restPath for the Service's Request DTO TRequest
  9
+		///		Maps the specified REST path to the specified request DTO.
10 10
 		/// </summary>
11  
-		/// <typeparam name="TRequest"></typeparam>
12  
-		/// <param name="restPath"></param>
13  
-		/// <returns></returns>
  11
+		/// <typeparam name="TRequest">The type of request DTO to map 
  12
+		///		the path to.</typeparam>
  13
+		/// <param name="restPath">The path to map the request DTO to.
  14
+		///		See <see cref="RestServiceAttribute.Path">RestServiceAttribute.Path</see>
  15
+		///		for details on the correct format.</param>
  16
+		/// <returns>The same <see cref="IServiceRoutes"/> instance;
  17
+		///		never <see langword="null"/>.</returns>
14 18
 		IServiceRoutes Add<TRequest>(string restPath);
15 19
 
16 20
 		/// <summary>
17  
-		/// Register the user-defined restPath, HTTP verbs it applies to (empty == all)
  21
+		///		Maps the specified REST path to the specified request DTO, and
  22
+		///		specifies the HTTP verbs supported by the path.
18 23
 		/// </summary>
19  
-		/// <typeparam name="TRequest"></typeparam>
20  
-		/// <param name="restPath"></param>
21  
-		/// <param name="verbs">comma-delimited verbs e.g. GET,POST,PUT,DELETE</param>
22  
-		/// <returns></returns>
  24
+		/// <typeparam name="TRequest">The type of request DTO to map 
  25
+		///		the path to.</typeparam>
  26
+		/// <param name="restPath">The path to map the request DTO to.
  27
+		///		See <see cref="RestServiceAttribute.Path">RestServiceAttribute.Path</see>
  28
+		///		for details on the correct format.</param>
  29
+		/// <param name="verbs">
  30
+		///		The comma-delimited list of HTTP verbs supported by the path, 
  31
+		///		such as "GET,PUT,DELETE".  Specify empty or <see langword="null"/>
  32
+		///		to indicate that all verbs are supported.
  33
+		/// </param>
  34
+		/// <returns>The same <see cref="IServiceRoutes"/> instance;
  35
+		///		never <see langword="null"/>.</returns>
23 36
 		IServiceRoutes Add<TRequest>(string restPath, string verbs);
24 37
 
25 38
 		/// <summary>
26  
-		/// Register the user-defined restPath, HTTP verbs it applies to (empty == all) and
27  
-		/// the defaultContentType the service should return if not specified by the client
  39
+		///		Maps the specified REST path to the specified request DTO, 
  40
+		///		specifies the HTTP verbs supported by the path, and indicates
  41
+		///		the default MIME type of the returned response.
28 42
 		/// </summary>
29  
-		/// <typeparam name="TRequest"></typeparam>
30  
-		/// <param name="restPath"></param>
31  
-		/// <param name="verbs">comma-delimited verbs e.g. GET,POST,PUT,DELETE</param>
32  
-		/// <param name="defaultContentType"></param>
33  
-		/// <returns></returns>
  43
+		/// <typeparam name="TRequest">The type of request DTO to map 
  44
+		///		the path to.</typeparam>
  45
+		/// <param name="restPath">The path to map the request DTO to.
  46
+		///		See <see cref="RestServiceAttribute.Path">RestServiceAttribute.Path</see>
  47
+		///		for details on the correct format.</param>
  48
+		/// <param name="verbs">
  49
+		///		The comma-delimited list of HTTP verbs supported by the path, 
  50
+		///		such as "GET,PUT,DELETE".
  51
+		/// </param>
  52
+		/// <param name="defaultContentType">
  53
+		///		The default MIME type in which the response object returned to the client
  54
+		///		is formatted, if formatting hints are not provided by the client.
  55
+		///		Specify <see langword="null"/> or empty to require formatting hints from
  56
+		///		the client.
  57
+		/// </param>
  58
+		/// <returns>The same <see cref="IServiceRoutes"/> instance;
  59
+		///		never <see langword="null"/>.</returns>
34 60
 		IServiceRoutes Add<TRequest>(string restPath, string verbs, string defaultContentType);
35 61
 
36  
-        /// <summary>
37  
-        /// Register the user-defined restPath, HTTP verbs it applies to (empty == all) and
38  
-        /// the defaultContentType the service should return if not specified by the client
39  
-        /// </summary>
40  
-        /// <param name="requestType"></param>
41  
-        /// <param name="restPath"></param>
42  
-        /// <param name="verbs">comma-delimited verbs e.g. GET,POST,PUT,DELETE.  Pass null to allow all verbs.</param>
43  
-        /// <param name="defaultContentType">Pass null to use default.</param>
44  
-        /// <returns></returns>
45  
-        IServiceRoutes Add(System.Type requestType, string restPath, string verbs, string defaultContentType);
  62
+		/// <summary>
  63
+		///		Maps the specified REST path to the specified request DTO, 
  64
+		///		specifies the HTTP verbs supported by the path, and indicates
  65
+		///		the default MIME type of the returned response.
  66
+		/// </summary>
  67
+		/// <param name="requestType">
  68
+		///		The type of request DTO to map the path to.
  69
+		/// </param>
  70
+		/// <param name="restPath">The path to map the request DTO to.
  71
+		///		See <see cref="RestServiceAttribute.Path">RestServiceAttribute.Path</see>
  72
+		///		for details on the correct format.</param>
  73
+		/// <param name="verbs">
  74
+		///		The comma-delimited list of HTTP verbs supported by the path, 
  75
+		///		such as "GET,PUT,DELETE".
  76
+		/// </param>
  77
+		/// <param name="defaultContentType">
  78
+		///		The default MIME type in which the response object returned to the client
  79
+		///		is formatted, if formatting hints are not provided by the client.
  80
+		///		Specify <see langword="null"/> or empty to require formatting hints from
  81
+		///		the client.
  82
+		/// </param>
  83
+		/// <returns>The same <see cref="IServiceRoutes"/> instance;
  84
+		///		never <see langword="null"/>.</returns>
  85
+		IServiceRoutes Add(System.Type requestType, string restPath, string verbs, string defaultContentType);
46 86
 	}
47 87
 }
102  src/ServiceStack.Interfaces/ServiceHost/RestServiceAttribute.cs
@@ -3,22 +3,56 @@
3 3
 namespace ServiceStack.ServiceHost
4 4
 {
5 5
 	/// <summary>
6  
-	/// Used to decorate Request DTO's to associate a RESTful request path mapping with a service
  6
+	///		Used to decorate Request DTO's to associate a RESTful request 
  7
+	///		path mapping with a service.  Multiple attributes can be applied to 
  8
+	///		each request DTO, to map multiple paths to the service.
7 9
 	/// </summary>
8 10
 	[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
9 11
 	public class RestServiceAttribute
10 12
 		: Attribute
11 13
 	{
  14
+		/// <summary>
  15
+		/// 	<para>Initializes an instance of the <see cref="RestServiceAttribute"/> class.</para>
  16
+		/// </summary>
  17
+		/// <param name="path">
  18
+		/// 	<para>The path template to map to the request.  See 
  19
+		///		<see cref="Path">RestServiceAttribute.Path</see>
  20
+		///		for details on the correct format.</para>
  21
+		/// </param>
12 22
 		public RestServiceAttribute(string path)
13 23
 			: this(path, null, null)
14 24
 		{
15 25
 		}
16 26
 
  27
+		/// <summary>
  28
+		/// 	<para>Initializes an instance of the <see cref="RestServiceAttribute"/> class.</para>
  29
+		/// </summary>
  30
+		/// <param name="path">
  31
+		/// 	<para>The path template to map to the request.  See 
  32
+		///		<see cref="Path">RestServiceAttribute.Path</see>
  33
+		///		for details on the correct format.</para>
  34
+		/// </param>
  35
+		/// <param name="verbs">A comma-delimited list of HTTP verbs supported by the 
  36
+		///		service.  If unspecified, all verbs are assumed to be supported.</param>
17 37
 		public RestServiceAttribute(string path, string verbs)
18 38
 			: this(path, verbs, null)
19 39
 		{
20 40
 		}
21 41
 
  42
+		/// <summary>
  43
+		/// 	<para>Initializes an instance of the <see cref="RestServiceAttribute"/> class.</para>
  44
+		/// </summary>
  45
+		/// <param name="path">
  46
+		/// 	<para>The path template to map to the request.  See 
  47
+		///		<see cref="Path">RestServiceAttribute.Path</see>
  48
+		///		for details on the correct format.</para>
  49
+		/// </param>
  50
+		/// <param name="verbs">A comma-delimited list of HTTP verbs supported by the 
  51
+		///		service.  If unspecified, all verbs are assumed to be supported.</param>
  52
+		/// <param name="defaultContentType">The default MIME type in which the response
  53
+		///		object returned to the client is formatted, if formatting hints are unspecified
  54
+		///		in the URL. Specify <see langword="null"/> or empty to require formatting
  55
+		///		hints from the client.</param>
22 56
 		public RestServiceAttribute(string path, string verbs, string defaultContentType)
23 57
 		{
24 58
 			Path = path;
@@ -26,10 +60,76 @@ public RestServiceAttribute(string path, string verbs, string defaultContentType
26 60
 			DefaultContentType = defaultContentType;
27 61
 		}
28 62
 
  63
+		/// <summary>
  64
+		///		Gets or sets the path template to be mapped to the request.
  65
+		/// </summary>
  66
+		/// <value>
  67
+		///		A <see cref="String"/> value providing the path mapped to
  68
+		///		the request.  Never <see langword="null"/>.
  69
+		/// </value>
  70
+		/// <remarks>
  71
+		///		<para>Some examples of valid paths are:</para>
  72
+		/// 
  73
+		///		<list>
  74
+		///			<item>"/Inventory"</item>
  75
+		///			<item>"/Inventory/{Category}/{ItemId}"</item>
  76
+		///			<item>"/Inventory/{ItemPath*}"</item>
  77
+		///		</list>
  78
+		/// 
  79
+		///		<para>Variables are specified within "{}"
  80
+		///		brackets.  Each variable in the path is mapped to the same-named property 
  81
+		///		on the request DTO.  At runtime, ServiceStack will parse the 
  82
+		///		request URL, exact the variable values, instantiate the request DTO,
  83
+		///		and assign the variable values into the corresponding request properties,
  84
+		///		prior to passing the request DTO to the service object for processing.</para>
  85
+		/// 
  86
+		///		<para>It is not necessary to specify all request properties as
  87
+		///		variables in the path.  For unspecified properties, callers may provide 
  88
+		///		values in the query string.  For example: the URL 
  89
+		///		"http://services/Inventory?Category=Books&ItemId=12345" causes the same 
  90
+		///		request DTO to be processed as "http://services/Inventory/Books/12345", 
  91
+		///		provided that the paths "/Inventory" (which supports the first URL) and 
  92
+		///		"/Inventory/{Category}/{ItemId}" (which supports the second URL)
  93
+		///		are both mapped to the request DTO.</para>
  94
+		/// 
  95
+		///		<para>Please note that while it is possible to specify property values
  96
+		///		in the query string, it is generally considered to be less RESTful and
  97
+		///		less desirable than to specify them as variables in the path.  Using the 
  98
+		///		query string to specify property values may also interfere with HTTP
  99
+		///		caching.</para>
  100
+		/// 
  101
+		///		<para>The final variable in the path may contain a "*" suffix
  102
+		///		to grab all subsequent segments in the path portion of the request URL and assign
  103
+		///		them to a single property on the request DTO.
  104
+		///		For example, if the path "/Inventory/{ItemPath*}" is mapped to the request DTO,
  105
+		///		then the request URL "http://services/Inventory/Category/Books/12345" will result
  106
+		///		in a request DTO whose ItemPath property contains "Category/Books/12345".
  107
+		///		You may only specify one such variable in the path, and it must be positioned at
  108
+		///		the end of the path.</para>
  109
+		/// </remarks>
29 110
 		public string Path { get; set; }
30 111
 
  112
+		/// <summary>
  113
+		///		Gets or sets a comma-delimited list of HTTP verbs supported by the service, such as
  114
+		///		"GET,PUT,POST,DELETE".
  115
+		/// </summary>
  116
+		/// <value>
  117
+		///		A <see cref="String"/> providing a comma-delimited list of HTTP verbs supported
  118
+		///		by the service, <see langword="null"/> or empty if all verbs are supported.
  119
+		/// </value>
31 120
 		public string Verbs { get; set; }
32 121
 
  122
+		/// <summary>
  123
+		///		Gets or sets the default MIME type in which the response 
  124
+		///		object returned to the client is formatted , when format hints 
  125
+		///		are not provided in the URI.  Some valid examples are such as 
  126
+		///		"application/json", or "application/xml".
  127
+		/// </summary>
  128
+		/// <value>
  129
+		///		A <see cref="String"/> providing the default MIME type of the response;
  130
+		///		<see langword="null"/> or empty if formatting hints are required 
  131
+		///		from the client.
  132
+		/// </value>
33 133
 		public string DefaultContentType { get; set; }
34 134
 	}
35 135
 
76  src/ServiceStack.ServiceInterface/RestServiceBase.cs
... ...
@@ -1,8 +1,14 @@
1 1
 using System;
  2
+using ServiceStack.Common.Web;
2 3
 using ServiceStack.ServiceHost;
3 4
 
4 5
 namespace ServiceStack.ServiceInterface
5 6
 {
  7
+	/// <summary>
  8
+	///		Base class for services that support HTTP verbs.
  9
+	/// </summary>
  10
+	/// <typeparam name="TRequest">The request class that the descendent class
  11
+	///		is responsible for processing.</typeparam>
6 12
 	public abstract class RestServiceBase<TRequest>
7 13
 		: ServiceBase<TRequest>,
8 14
 		IRestGetService<TRequest>,
@@ -16,6 +22,20 @@ protected override object Run(TRequest request)
16 22
 			throw new NotImplementedException("This base method should be overridden but not called");
17 23
 		}
18 24
 
  25
+		/// <summary>
  26
+		///		The method may overriden by the descendent class to provide support for the 
  27
+		///		GET verb on <see cref="TRequest"/> objects.
  28
+		/// </summary>
  29
+		/// <param name="request">The request object containing parameters for the GET
  30
+		///		operation.</param>
  31
+		/// <returns>
  32
+		///		A response object that the client expects, <see langword="null"/> if a response
  33
+		///		object is not applicable, or an <see cref="HttpResult"/> object, to indicate an 
  34
+		///		error condition to the client. The <see cref="HttpResult"/> object allows the 
  35
+		///		implementation to control the exact HTTP status code returned to the client.  
  36
+		///		Any return value other than <see cref="HttpResult"/> causes the HTTP status code 
  37
+		///		of 200 to be returned to the client.
  38
+		/// </returns>
19 39
 		public virtual object OnGet(TRequest request)
20 40
 		{
21 41
 			throw new NotImplementedException("This base method should be overridden but not called");
@@ -38,6 +58,20 @@ public object Get(TRequest request)
38 58
 			}
39 59
 		}
40 60
 
  61
+		/// <summary>
  62
+		///		The method may overriden by the descendent class to provide support for the 
  63
+		///		PUT verb on <see cref="TRequest"/> objects.
  64
+		/// </summary>
  65
+		/// <param name="request">The request object containing parameters for the PUT
  66
+		///		operation.</param>
  67
+		/// <returns>
  68
+		///		A response object that the client expects, <see langword="null"/> if a response
  69
+		///		object is not applicable, or an <see cref="HttpResult"/> object, to indicate an 
  70
+		///		error condition to the client. The <see cref="HttpResult"/> object allows the 
  71
+		///		implementation to control the exact HTTP status code returned to the client.  
  72
+		///		Any return value other than <see cref="HttpResult"/> causes the HTTP status code 
  73
+		///		of 200 to be returned to the client.
  74
+		/// </returns>
41 75
 		public virtual object OnPut(TRequest request)
42 76
 		{
43 77
 			throw new NotImplementedException("This base method should be overridden but not called");
@@ -60,6 +94,20 @@ public object Put(TRequest request)
60 94
 			}
61 95
 		}
62 96
 
  97
+		/// <summary>
  98
+		///		The method may overriden by the descendent class to provide support for the 
  99
+		///		POST verb on <see cref="TRequest"/> objects.
  100
+		/// </summary>
  101
+		/// <param name="request">The request object containing parameters for the POST
  102
+		///		operation.</param>
  103
+		/// <returns>
  104
+		///		A response object that the client expects, <see langword="null"/> if a response
  105
+		///		object is not applicable, or an <see cref="HttpResult"/> object, to indicate an 
  106
+		///		error condition to the client. The <see cref="HttpResult"/> object allows the 
  107
+		///		implementation to control the exact HTTP status code returned to the client.  
  108
+		///		Any return value other than <see cref="HttpResult"/> causes the HTTP status code 
  109
+		///		of 200 to be returned to the client.
  110
+		/// </returns>
63 111
 		public virtual object OnPost(TRequest request)
64 112
 		{
65 113
 			throw new NotImplementedException("This base method should be overridden but not called");
@@ -82,6 +130,20 @@ public object Post(TRequest request)
82 130
 			}
83 131
 		}
84 132
 
  133
+		/// <summary>
  134
+		///		The method may overriden by the descendent class to provide support for the 
  135
+		///		DELETE verb on <see cref="TRequest"/> objects.
  136
+		/// </summary>
  137
+		/// <param name="request">The request object containing parameters for the DELETE
  138
+		///		operation.</param>
  139
+		/// <returns>
  140
+		///		A response object that the client expects, <see langword="null"/> if a response
  141
+		///		object is not applicable, or an <see cref="HttpResult"/> object, to indicate an 
  142
+		///		error condition to the client. The <see cref="HttpResult"/> object allows the 
  143
+		///		implementation to control the exact HTTP status code returned to the client.  
  144
+		///		Any return value other than <see cref="HttpResult"/> causes the HTTP status code 
  145
+		///		of 200 to be returned to the client.
  146
+		/// </returns>
85 147
 		public virtual object OnDelete(TRequest request)
86 148
 		{
87 149
 			throw new NotImplementedException("This base method should be overridden but not called");
@@ -104,6 +166,20 @@ public object Delete(TRequest request)
104 166
 			}
105 167
 		}
106 168
 
  169
+		/// <summary>
  170
+		///		The method may overriden by the descendent class to provide support for the 
  171
+		///		PATCH verb on <see cref="TRequest"/> objects.
  172
+		/// </summary>
  173
+		/// <param name="request">The request object containing parameters for the PATCH
  174
+		///		operation.</param>
  175
+		/// <returns>
  176
+		///		A response object that the client expects, <see langword="null"/> if a response
  177
+		///		object is not applicable, or an <see cref="HttpResult"/> object, to indicate an 
  178
+		///		error condition to the client. The <see cref="HttpResult"/> object allows the 
  179
+		///		implementation to control the exact HTTP status code returned to the client.  
  180
+		///		Any return value other than <see cref="HttpResult"/> causes the HTTP status code 
  181
+		///		of 200 to be returned to the client.
  182
+		/// </returns>
107 183
 		public virtual object OnPatch(TRequest request)
108 184
 		{
109 185
 			throw new NotImplementedException("This base method should be overridden but not called");

0 notes on commit bad04c6

Please sign in to comment.
Something went wrong with that request. Please try again.