Parameter Aliases in SharePoint REST

This relatively brief post will explain what a Parameter Alias is in OData. They’re used in examples throughout the SharePoint REST API Documentation, and there is a brief description of them (see references), but they are not very well explained. The basic syntax looks like:

For a concrete example, I’ll start with the following REST call:

The result of just getting a list through REST is that you get back the list schema, which contains a lot of information about the list. But since I passed in $select=Ttitle, I only get back the title like so:

I’ll be the first to admit that this isn’t overly useful, I get back the list title but had to supply the list title to get it? But that’s not the point, I just wanted to start with a simple example and show how it can be altered with parameter aliasing, so here is that example:

So I’ve passed in my title to getByTitle as @Target, which is the parameter alias. Then I specify the value for the parameter alias later in the URL as a query parameter. Of note:

• A parameter alias must start with the “at symbol” @
• The parameter alias value is passed in the URL as a request parameter (i.e. @Target=’SalesDivision’)
• The parameter alias value must be exactly what you would have typed where the parameter is used. For instance, in the above example I passed in ‘SalesDivision’ so that’s what I put in for my parameter value (quotes and all). So if the parameter had been an integer, the value would have just been a raw number, and if it had been a guid it would have looked like guid’54bff8cc-6585-4890-9870-3b5b5e64ba6a’
• If a string literal containing the list title were an argument to more than one function call in the URL, I could have reused the same parameter alias in both places
• Complex types (i.e. objects) cannot be aliased in calls to SharePoint REST services

Here is a call to Lists/getById, passing in a GUID as a parameter alias:

So what’s the point? They don’t actually provide a great deal of functionality. They just provide a short-cut syntax to make your URLs more readable. A GUID is pretty big and ugly, so if a URL contains the same GUID multiple times, or multiple GUIDs, or any arguments where the value is excessively long, it can be hard to decipher the intent of the URL. Using a short-cut throughout the URL and defining it’s actual value at the end can make the intent of the URL easier to understand. Even if you don’t buy that argument, you will see them used throughout the Microsoft documentation for the SharePoint REST API and other people’s code, so you should understand them.

Forgetting to include the single quotes in a string literal defined as a parameter alias, or forgetting to tack on the word guid, or even inadvertently adding single quotes to what’s supposed to be integer parameter; well any one of these will earn you a one-way ticket to Azkaban…err…or at least lead to a bit of head scratching.

Mostly, my advice wrt parameter aliasing is that if something isn’t working with it, try rewriting it without it, and usually you’re error will quickly be apparent. That extra level of indirection can sometimes throw you off. Once you get the query working without parameter aliases, replace your more dynamic or longer parameters with aliases one at a time and test again. Getting your URLs correct before trying to write code will save you a lot of time and is where running your URLs in the browser console can be useful (as you’ll see I do frequently throughout my blog posts). If you find using the console to test your URLs is too cumbersome, and you have the luxury of being able to install browser plugins, a plugin like SP REST Client for chrome can simplify your life quite a bit.

There is another similar thing briefly described in the OData specification called parameter name syntax (the Microsoft documentation calls this query string syntax, but since the query string is also used for OData operators and parameter aliases I’ll stick with the spec terminology). It does work in SharePoint as well, and this is an example of the same REST call using parameter name syntax:

For the last function call in a URL, you can remove the parameter list altogether (including parens), and then specify all of the parameters as request parameters using parameter name equals parameter value. Now in the case of parameter aliases, I arbitrarily choose a name like @Target. But with parameter name syntax, the name is chosen by web service implementer and cannot be changed by the caller. You must match the name in the implementation (case insensitive).

I’m not crazy about this syntax. I think it obfuscates the URLs rather than making them easy to read. And why only the last function? The reason of course is that different functions might use the same parameter name in different contexts, and how would that get resolved? I also haven’t seen this used in either the Microsoft documentation, or examples I see on the web for SharePoint REST calls, only in the OData specification. So while it does work in SharePoint, parameter aliases are more flexible and easier to read, and I would generally avoid using parameter name syntax. Just a personal preference.

Anyway, here is an example of two different parameter aliases, for two different functions, in a single URL:

This is a contrived example, but we can probably agree that with a URL like:

it’s easier to understand the intent of the URL, than the equivalent URL when expressed like this:

I said earlier that parameter aliases don’t add that much functionality, and it’s true. It’s certainly not rocket science. That said, I’ll probably use them in pretty much every query URL I write from now on. And I’ll use them specifically for the more dynamic function arguments. Say I’m writing crud operations for a content type. The URLs for that are probably pretty static, except the list title/id and the id of the item we’re currently working with. So those are my two parameter aliases. And generally, I’ll define my parameter alias values at the end of the query parameters, after the OData operators. It just puts the most important information up front making the URLs easier to read and understand.

One more quick point: according to the OData specification, parameter aliases can also be used within certain OData operator values, like $filter and $orderBy. I haven’t been able to make this work in SharePoint. But I don’t exactly get the feeling that my life would be more fullfilled if I could get this to work. After all, they’re called parameter aliases, not operator aliases; it makes sense to me that they would work on parameters and not necessarily on operators.

References

• Using parameter aliases in REST service calls