| NuGet package | Owin.Framework.Pages.Restful |
| GitHub source | OwinFramework.Pages.Restful |
Attach this attribute to a class to identify it as a web service. To register this service with the router and send requests to it you can get the fluent builder to scan the assembly containing your class, or you can register it in code.
[IsService("order", "/order/", new[] { Method.Post, Method.Get, Method.Put, Method.Delete })]
public class OrderService
{
[Endpoint(UrlPath = "{id}", Methods = new[] { Method.Get })]
public void Get(IEndpointRequest request)
{
throw new NotImplementedException();
}
}
The [IsService()] attribute has properties that specify how Http requests are routed to the service as folllows.
This property of the [IsService()] attribute establishes a route for the service. Any Http requests that match this at the start of their path will be compared to the service endpoints for possible routing to that endpoint. If the base path does not match the Http request then this service is skipped and routing moves onto the next service.
For efficiency you should always specify a base path for each service and organize your service endpoints so that all the endpoints in a serice have the same base path. This arrangement provides the most efficient routing of requests.
If you do not specify a base path then it defaults to / effectively making all of endpoints within the service have absolute paths.
The base path should end with a forward slash because it is concatenated with the relative path of each endpoint to form the full path of the endpoint. If you forget to append a forward slash then one will be appended automatically for you.
The base path can contain wildcards for some path elements but must not end with a wildcard. Since it is designed to match the start of the Http request it will be added to the routing table with ** on the end allowing the endpoints to have any relative path below this base.
This property of the [IsService()] attribute defines the Http methods that will be routed to the service. If you do not specify the Methods it will default to new []{ Method.Post }. In this case the service will only receive Http POST requests. To handle other kinds of Http request you must set the Methods property.
You can route all Http methods to the service by setting Methods to an empty array like this: new Method[]{ }
Only methods that are routed to the service itself can be further routed to the endpoints within the service with relative paths. Endpoints with absolute paths are chained into the routing at the root level and do not have this restriction.
This property of the [IsService()] attribute defines the order in which routing will be evaluated. The highest priority routes are considered before the lower priority ones. Since the default priority is zero, the recommentation is to make very specific routes have positive priorities and wildcard routes have negative priority so that the wildcard routes do not mask the more specific routes by matching the request first.
Priorities also affect performance because the router will try to match routes in order or highest to lowest priority until it finds a match. You can make routing more efficient by giving higher priority to routes that are matched more frequently.
Set this property to define how detailed are the analytics that are measured for the endpoints of this service. You can use intellisense to see the possible values for this property.
Defines the type of deserializer to use when the body of the request is accessed for the first time by the application code. Setting this on the service makes it the default deserializer for all endpoints in this service, but it can also be overidden for each endpoint.
The deserializer is specified as a class type to use. This class type must implement the IRequestDeserializer interface.
The standard libraries already contain some implementations of IRequestDeserializer that you can take advantage of in your application, but this interface is also straightforward to implement. These classes are in the OwinFramework.Pages.Restful.Serializers namespace.
Set this property to define how objects returned from service endpoints are written to the http response. The default serializer serializes the returned object to Json using the NewtonSoft serializer.
Setting this property on the service makes it the default for all of the service endpoints, but this can also be overidden for each endpoint.
The serializer is specified as a class type to use. This class type must implement the IResponseSerializer interface. There are implementations of this interface in the OwinFramework.Pages.Restful.Serializers namespace.
Setting this property means that identities that call this endpoints of this service will have to have this permission assigned to them in the authorization middleware. Setting this property on the service makes it the default for all endpoints of the service. The value can be overidden for each enpoint if desired.
Note that this property only has effect if your application includes authorization middleware in the Owin pipeline.
When this property is true the name of the service and method name are passed as the asset name to the authentication check separated by a forward slash. This allows you to define permissions that allow access to service methods using wildcards, for example you can give one group of users permission to call any endpoint in the service whilst other groups of users can only call certain specific endpoints.
This property defines the name of a parameter to the endpoint that will be passed to the authorization check at the asset value. For example you can have an endpoint that updates a users avatar that takes userId as a parameter, then you can set "userId" as the value of the ParameterSpecificPermission, in which case the value of the userId parameter will be passed to the authorization middleware as the asset name, and you can configure the authorization middleware to only grant this permission if the user id is your own user id. You can also define a group of users in the authorization middleware who can call this endpoint for any user id.
This parameters allows you to define different versions of your service for different segments of users in A/B testing scenarios.
Endpoints can have relative or absolute paths. This decision fundamentally changes the routing model for the endpoint.
When endpoints have a relative url path (that does not begin with a forward slash) the endpoint is considered to be within the service and only requests routed to that service can end up at this endpoint.
When endpoints have an absolute url path (that begins with a forward slash) the endpoint is included directly into the root routing table and is indendant of any routing applied to the containing service. In this case there is still advantages in building a service with multiple endpoints because they inherit the settings for serialization, deserialization etc.