Uri Template

Uri Template is what describes an operation's "endpoint address relative" part. A Uri Template may include constants, parameterized variables, masks and default values. Sentinet allows flexible and powerful syntax for Uri Templates. This syntax is fully compliant with Microsoft UriTemplate syntax, described at https://msdn.microsoft.com/en-us/library/system.uritemplate.aspx.

Note

A URI template allows you to define a set of structurally similar URIs. Templates are composed of two parts, a path and a query. A path consists of a series of segments delimited by a slash (/). Each segment can have a literal value, a variable value (written within curly brackets { }, constrained to match the contents of exactly one segment), or a wildcard (written as an asterisk *, which matches "the rest of the path"), which must appear at the end of the path. The query expression can be omitted entirely. If present, it specifies an unordered series of name/value pairs. Elements of the query expression can be either literal pairs (?x=2) or variable pairs (?x={xval}). Unpaired values are not permitted. The following examples show valid template strings:

• weather/WA/Seattle

• weather/{state}/{city}

• weather/*

• weather/{state}/{city}?forecast=today

• weather/{state}/{city}?forecast={day}

The preceding URI templates might be used for organizing weather reports. Segments enclosed in curly brackets are variables, and everything else is literal. You can convert an UriTemplate instance into a Uri by replacing variables with actual values. For example, taking the template "weather/{state}/{city}" and putting in values for the variables "{state}" and "{city}" gives you "weather/WA/Seattle". Given a candidate URI, you can test whether it matches a given URI template by calling Match(Uri, Uri). You can also use UriTemplate instances to create a Uri from a set of variable values by calling BindByName(Uri, NameValueCollection) or BindByPosition(Uri, String[]).

Sentinet also allows for parametrized tokens in the URI templates, for example /{filename}.json or /document_{number}.

Unless the REST API is registered from an existing Swagger (v2) or OpenAPI (v3) document, Sentinet users decide how a service operation should be defined. For example, Sentinet users can register a single operation (resource) called ManageOrder that is defined with an operation's Uri template that includes additional query parameters where action's parameterized value {action} can have value of create, update or delete to actually create, update or delete an order by the same service operation:

Operation: ManageOrder

Operation Uri template: /ManageOrder?action={action}&orderId={orderId}&orderDetails={orderDetails}

Alternatively, the same service can be designed and registered with three distinct operations: CreateOrder, UpdateOrder and DeleteOrder:

Operation: CreateOrder

Operation Uri template: /CreateOrder?orderDetails={orderDetails}

Operation: UpdateOrder

Operation Uri template: /UpdateOrder?orderId={orderId}&orderDetails={orderDetails}

Operation: DeleteOrder

Operation Uri template: /DeleteOrder?orderId={orderId}

And yet another API design for the same service can be based on a resource-oriented (HTTP verb or HTTP method) approach where all three operations are still distinct, but differentiated by an HTTP verb, PUT, UPDATE and DELETE.

Whatever approach an API designer selects, Sentinet will support it through its flexible REST services description syntax.