Revisiting REST Versioning
Posted by Scott Seely in Uncategorized on November 19, 2012
I was recently asked what my opinion was on REST versioning, a few years after having written http://www.informit.com/articles/article.aspx?p=1566460 and after having recorded some stuff for Pluralsight on versioning as well. The questions were general purpose enough that I thought I’d share my answer on the blog. Here are the questions and my answers:
1. Given 2.5 years since the article, have you seen any shift toward one or the other method in the industry?
What I’ve seen in behavior is that people only change the URL for breaking changes. They try like crazy to always use the same endpoint for everything, including new functionality. I have seen a lot of uptake with the WebAPI bits released in .NET 4.5. Some companies have gone NUTS on the ability to negotiate content types, and this is for applications for big companies with thousands to millions of customers.
For APIs meant to be consumed by less process oriented folks, I see more APIs that just use JSON. The API owner then documents things for internal SDK development teams. What appears to happen is the internal SDK development teams ‘test’ the docs by building APIs in .NET, Ruby, PHP, Java, Objective C, and so on. When this phase is done, the QA’d REST documents and resulting SDK documentation is published. Development of an SDK seems to be done in an effort to make API adoption easier and to reduce the amount of support needed to get API consumers up and running.
If I was leading a REST API development project, I would design a good structure, document whatever the team did for the REST API, and then lean on the SDK as the only well supported mechanism for accessing the API. This move would let the team build a nice SDK without worrying about making sure everyone can understand the REST documentation. The reality is that most developers do not know and do not want to fully understand the intricacies of content negotiation, cache headers, and so on. They just want to build software. Your job is to worry about these things and a good SDK makes it easier for all users to do the right things.
2. If you were building a new API today what direction would you go?
I’m reading this as a SOAP question as well as a “how do I build a REST endpoint today?” question. The answer is: it depends. If I need the API to be consumed by internal endpoints, SOAP gives me a faster way to build things and, since the app is internal, it’s highly likely that transaction consistency, security, and an RPC-like calling convention fit in well with the existing needs. I’d still version endpoints as much as I could, but reality is that most places roll out new versions of systems that need to be versioned in lockstep due to business and regulatory concerns that versioning simply does not care about. Oftentimes, the reason for the new version is new requirements that make the old version obsolete.
For external APIs, I’d only ever use HTTP based APIs. Then, the question is obviously: do you create new media types and use content negotiation, do you use new endpoints for version changes, or do you use something else? My preference today is to use new endpoints and worry about wiring things up correctly under the covers. Doing this allows me to monitor usage of each version using existing HTTP log scraping tools and seeing which URLs are being used most heavily. For everything else: how RESTful I am vs. just using HTTP as an RPC mechanism, data types, payloads, and so on, I’d stick with building SDKs as the preferred method to interact with the service. I value good design but I hate arguing about things like whether or not the ETags are configured correctly. The SDK documents the API team’s decisions where those arguments happened and let’s everyone else just use things.
3. Do you know of any particularly good resources on the topic of the top of your head that don’t come up in google and bing?
Actually, no. It seems like a lot of great stuff was written about designing REST APIs and what I’ve found on the various search engines all seems pretty decent. Today, tools like WebAPI from Microsoft and others make it easy to do the right things as an API developer.
Directing Service Bus to Communicate on HTTP Only
Posted by Scott Seely in Azure, Service Bus, WCF on September 7, 2012
Many folks have constraints in their data centers, frequently relating to which incoming and outgoing ports they can open up. Many times, they are restricted to only using well known ports, like HTTP (80) and HTTPS (433). When using the Windows Azure Service Bus and just using the defaults, you get some unexpected behavior. The Service Bus will still use TCP ports to do some of the back channel conversations such as keep-alive type polling that occurs to redirect requests from the Service Bus to your instance of the hosted service. To fix this up, you need to do one simple thing: tell the ServiceBusEnvironment to only use HTTP. In your application startup code, add this line so that Service Bus only speaks over ports 80/433:
ServiceBusEnvironment.SystemConnectivity.Mode = ConnectivityMode.Http;
If you are on IIS, this code would go in the Application_Start override of global.asax.cs. If you are self-hosted, this goes into your main() method as one of your first lines of code.
If you want to troubleshoot and see if this is indeed the cause of your issues in your data center, look at the ports your application is opening up. Ports in the 7390-7395 range are coming from Service Bus. You’ll be able to detect this through your network monitoring infrastructure or tools like WireShark. Make the change I suggest, then check again. Your port issues should be resolved.
Windows 8 Lists: Sizing the list item
Posted by Scott Seely in Windows 8, XAML on August 31, 2012
This past week, I was helping out at a “hack day” at the Microsoft offices in Downers Grove, IL. One of the attendees had an interesting problem: he wanted the contents of his list to dynamically expand to take up the full width of the ListView. The type of item doesn’t matter, so I picked something with 4 properties for the display that would allow me to exercise core of the issue and nothing more.
public class Class1 { public string One { get; set; } public string Two { get; set; } public string Three { get; set; } public string Four { get; set; } }
This was then bound to a ListView using the following XAML (with a border on each item to help visualize how big the actual template wound up being):
<ListView Name="ListView1"> <ListView.ItemTemplate> <DataTemplate> <Border BorderBrush="Red" BorderThickness="2"> <Grid> <Grid.ColumnDefinitions> <ColumnDefinition Width="1*"/> <ColumnDefinition Width="1*"/> <ColumnDefinition Width="1*"/> <ColumnDefinition Width="6*"/> </Grid.ColumnDefinitions> <TextBlock Grid.Column="0" Text="{Binding One}"/> <TextBlock Grid.Column="1" Text="{Binding Two}"/> <TextBlock Grid.Column="2" Text="{Binding Three}"/> <TextBlock Grid.Column="3" Text="{Binding Four}"/> </Grid> </Border> </DataTemplate> </ListView.ItemTemplate> </ListView>
So far, so good, but when the app displayed the collection of Class1 objects, we saw that the ItemTemplate didn’t extend across the screen.
This little item did not do what we wanted it to do, so we thought about what the problem was. A Grid wants to expand to the size of it’s surroundings when not given a limit. The container it was given was one where it was told to size to as big as it needed and no more. As a result, the Grid reported back that it needed to be big enough for the 4 TextBlocks and then was only given that space. Was there a way to go bigger? We looked at the properties and saw one on the ListView called HorizontalContentAlignment, which appeared to let the items align Center, Left, Right, or to Stretch. Stretch usually does good things, so we tried that:
<ListView Name="ListView1" HorizontalContentAlignment="Stretch">
The end result: no change. The screen looked the same as before. At that point, we remembered that we could set the width of the grid manually. Setting the width manually, we were able to achieve the effect, but would still lose any adaptive layout as the screen geometry changed. Still, knowing that the Grid Width property would solve the problem, we only had to find a way to bind the Width of the Grid to the Width of the ListView. On the Grid, we tried binding its width to the Width of ListView 1:
<Grid Width="{Binding ElementName=ListView1, Path=Width}">
Again, no real change. So, we went a bit further. We remembered that we could hook to the SizeChanged event on the ListView and then change a property on the page to feed things. For properties that can be linked to, one can use a combination of DependencyProperty and a value to keep things in sync or implement INotifyPropertyChanged and bind to that value. We tried both paths and found that the DependencyProperty was less code and easier to understand for a control. For this, we added the following to the Page code:
static DependencyProperty ListView1WidthProperty = DependencyProperty.Register("ListView1Width", typeof(double), typeof(MainPage), new PropertyMetadata(10)); public double ListView1Width { get { return (double)(GetValue(ListView1WidthProperty)); } set { SetValue(ListView1WidthProperty, value); } }
This code just gave us something to hook into. We then added some code to handle the SizeChanged event on the ListView, which would update the value for ListView1Width:
private void ListView1_SizeChanged(object sender, Windows.UI.Xaml.SizeChangedEventArgs e) { ListView1Width = e.NewSize.Width - 15; }
This method was hooked up in the XAML as:
<ListView Name="ListView1" SizeChanged="ListView1_SizeChanged">
We then gave the Page the name MyPage in order to allow us to bind to the ListView1Width property. The Grid Width property was now bound as:
<Grid Width="{Binding ElementName=MyPage, Path=ListView1Width}">
The final results were exactly what we wanted:
And, as the list was resized to take advantage of other items, like the snap view or portrait view, the resize continued to work.
Assets:
The XAML for this page:
<Page
x:Class="ColumnsInList.MainPage"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:local="using:ColumnsInList"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d"
Name="MyPage" >
<Grid Name="BigGrid" Background="{StaticResource ApplicationPageBackgroundThemeBrush}">
<ListView Name="ListView1" SizeChanged="ListView1_SizeChanged">
<ListView.ItemTemplate>
<DataTemplate>
<Border BorderBrush="Red" BorderThickness="2">
<Grid Width="{Binding ElementName=MyPage, Path=ListView1Width}">
<Grid.ColumnDefinitions>
<ColumnDefinition Width="1*"/>
<ColumnDefinition Width="1*"/>
<ColumnDefinition Width="1*"/>
<ColumnDefinition Width="6*"/>
</Grid.ColumnDefinitions>
<TextBlock Grid.Column="0" Text="{Binding One}"/>
<TextBlock Grid.Column="1" Text="{Binding Two}"/>
<TextBlock Grid.Column="2" Text="{Binding Three}"/>
<TextBlock Grid.Column="3" Text="{Binding Four}"/>
</Grid>
</Border>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Grid>
</Page>
C# Code:
// Class1.cs namespace ColumnsInList { public class Class1 { public string One { get; set; } public string Two { get; set; } public string Three { get; set; } public string Four { get; set; } } } // MainPage.xaml.cs using System.Collections.ObjectModel; using Windows.UI.Xaml; using Windows.UI.Xaml.Controls; using Windows.UI.Xaml.Navigation; namespace ColumnsInList { public sealed partial class MainPage : Page { static DependencyProperty ListView1WidthProperty = DependencyProperty.Register("ListView1Width", typeof(double), typeof(MainPage), new PropertyMetadata(10)); public double ListView1Width { get { return (double)(GetValue(ListView1WidthProperty)); } set { SetValue(ListView1WidthProperty, value); } } public MainPage() { this.InitializeComponent(); } protected override void OnNavigatedTo(NavigationEventArgs e) { ListView1.ItemsSource = new ObservableCollection<Class1>(new Class1[] { new Class1{One="One1", Two = "Two1", Three ="Three1", Four= "Four1"}, new Class1{One="One2", Two = "Two2", Three ="Three2", Four= "Four2"}, new Class1{One="One3", Two = "Two3", Three ="Three3", Four= "Four3"}, new Class1{One="One4", Two = "Two4", Three ="Three4", Four= "Four4"}, }); } private void ListView1_SizeChanged(object sender, Windows.UI.Xaml.SizeChangedEventArgs e) { ListView1Width = e.NewSize.Width - 15; } } }
Body Scanners, Fluoroscopes, and the TSA
Posted by Scott Seely in Uncategorized on July 12, 2012
From the 1920s through about 1960, shoe stores used an amazing device to sell shoes: the fluoroscope. Depending on the year, the reason behind the device changed; it helped you fit the shoe better, it revealed any issues in your foot, it was cool to see the bones in your foot move. The fluoroscope achieved this magic through x-rays. By the 1950s, people understood that being exposed to lots of x-rays was really bad for people. Overexposure to x-rays increases the odds you get various cancers. In 1957, Pennsylvania started a pattern of governments banning the devices(http://www.smithsonianmag.com/history-archaeology/Heres_Looking_at_You_Kids.html). The fears were along the lines of the following:
- Growing people (kids) shouldn’t be exposed to this many x-rays.
- Lots of x-rays were taken of the salespeople.
Think about #2. According to http://www.orau.org/ptp/collection/shoefittingfluor/shoe.htm, people got radiation burns and cancers from lots of exposures.
Many shoe salespersons put their hands into the x-ray beam to squeeze the shoe during the fitting. As a result, one saleswoman who had operated a shoe fitting fluoroscope 10 to 20 times each day over a ten year period developed dermatitis of the hands. One of the more serious injuries linked to the operation of these machines involved a shoe model who received such a serious radiation burn that her leg had to be amputated (Bavley 1950).
Interestingly enough, the Transportation Security Administration has installed thousands of x-ray machines as full body scanners. Frequent travelers are getting x-rayed several times a week. TSA employees are getting nearby exposure scans hundreds of times per day. Because of concerns around the health effects, a case was brought and was decided against the TSA that they need to figure out if these machines are safe. Our executive branch needs to enforce this ruling, but so far have chosen not to enforce it.
If you have some time today, I recommend that you go to https://petitions.whitehouse.gov/petition/require-transportation-security-administration-follow-law/tffCTwDd and sign the petition to get the executive branch to carry out the decision of the judicial branch.
Validating a WRAP ACS token in node.js
Posted by Scott Seely in Uncategorized on January 2, 2012
A few friends and I are building a system for home automation. Specifically, it is an application that opens and closes a garage door. One of the design decisions was to write the server side in node.js but to use Azure when it made sense. One of the Azure features we are using is the Access Control Service. When a client presents a token, you need to make sure that the signature on that token is valid. That turns out to be fairly interesting if you are new to node.js and have never used it before. I fit that model well. After a lot of tinkering and learning, I was able to write a function that validated a wrap_access_token using node.js and some associated, standard libraries. Here is the code, in its entirety. I include some ‘test’ code as well to allow others to verify results. I’ve already rotated the ACS signing key so that I don’t breach security too badly. This whole thing works surprisingly well.
In case you can’t read the code too well, here is what it does:
1. Parse the token into it’s constituent parts.
2. Pass the wrap_access_token to the function, along with the associated key.
Within the function:
1. Remove the signature part from the token since we need to verify that we generate the same signature. Since the signature is generated based on the bytes that precede it, the signature can’t be part of itself (this part is obvious when you think of it; the hard part is remembering to think of it!)
2. Unescape the signature and remember the base64 version of the signature, which is really just a byte array.
3. Generate the SHA256 HMAC signature using the shared secret/key.
4. Verify that the base64 encoding of the digest that we generated matches the one that was sent it.
5. If the signature passed in matches the one we generated, then the other entity knows the secret and can be trusted to have signed the tokens.
6. Party on, because the claims are valid.
The code would next need to split out the claims. The claims are just form-encoded key value pairs within the wrap_access_token. That step is left as an exercise for the reader.
var crypto = require(‘crypto’);
var util = require(‘util’);
var querystring = require(‘querystring’);
var buffer = require(‘buffer’);
function ValidateToken(token, key){
var hmacToken = “&HMACSHA256=”;
var indexOfToken = token.indexOf(hmacToken) + hmacToken.length;
var swtSignature = querystring.unescape(token.substr(indexOfToken, token.length – indexOfToken));
var signedPiece = token.substr(0, indexOfToken – hmacToken.length);
var buffer = new Buffer(key, encoding=”base64″);
var hmac = crypto.createHmac(“sha256″, buffer);
hmac.update(signedPiece);
var digest = hmac.digest(encoding=”base64”);
return digest == swtSignature;
}
var theToken = “wrap_access_token=developersmackdown.garage%3dOpenClose%26http%253a%252f%252fschemas.microsoft.com%252faccesscontrolservice%252f2010%252f07%252fclaims%252fidentityprovider%3dhttps%253a%252f%252ffriseton.accesscontrol.windows.net%252f%26Audience%3dhttp%253a%252f%252fcontosocontacts%252f%26ExpiresOn%3d1325287532%26Issuer%3dhttps%253a%252f%252ffriseton.accesscontrol.windows.net%252f%26HMACSHA256%3dSrgqXJv9pkxjweT2Lr%252bIV%252fGAncqIc34SnbrHdbr3VOQ%253d&wrap_access_token_expires_in=5999”;
var theData = querystring.parse(theToken, sep=’&’, eq=’=’);
var theKey = “Bn7TfLML5wK+R5TAa2VrO/9JANwuk3lzt/ykc4no+h0=”;
util.puts(ValidateToken(theData.wrap_access_token, theKey));
REST Presentation at Chicago Software Development Community in Oakbrook
Posted by Scott Seely in Uncategorized on November 7, 2011
Thanks again to everyone who showed up for my presentation on REST at the Microsoft Store in Oakbrook. I’ve posted the slides and demos here. It was a great time. I’ve never presented in a store, never had a component of the “audience” that was just shopping either. It was an interesting, unique experience to say the least! I also enjoyed the conversations afterwards.
My Windows Azure Caching Service talk from DevConnections
Posted by Scott Seely in Uncategorized on November 2, 2011
I just presented my Windows Azure Caching Service talk. Thanks to everyone who attended. The audience was small, but I love that you all asked so many great questions. Here are the slides and demos from the talk. I’ll be giving this talk again at the Midwest Cloud Computing User Group in the Chicago area on November 15. You can register for it at http://www.communitymegaphone.com/ShowEvent.aspx?EventID=4709.
The slides and demos from the content at DevConnections is here.
Talk and demos from CNUG, AppFabric Talk
Posted by Scott Seely in Uncategorized on July 21, 2011
Last night I had a chance to speak about Windows Azure AppFabric at the Chicago .NET Users’ Group. Thanks to everyone who came out! I had a great time. A few of you really wanted the slides ASAP. I’ve cleaned out my keys and namespaces from the demos, so they don’t run at the moment (but they will build!). You can get them here: https://friseton.blob.core.windows.net/downloads/CNUG-AppFabric-2011-07-20.zip.
You’ll need to install a few things and create a few accounts if you want to run any of the demos:
Tools:
1. Getting started links for Windows Azure: http://www.microsoft.com/windowsazure/learn/getstarted/
2. Windows Azure AppFabric SDK 1.0: http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=19925 (for production AppFabric)
3. Windows Azure AppFabric SDK 2.0: http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=17691 (for the CTP bits: queues, topics, etc.)
4. More training on Windows Azure: https://www.pluralsight-training.net/microsoft/OLT/subscribe/Subscribe1.aspx?freetrial=true&planHint=Monthly (10 day free trial– totally worth it, but I am an instructor there too;) )
AppFabricLabs and the ServiceBus
Posted by Scott Seely in Uncategorized on May 20, 2011
This week, the Windows Azure AppFabricLabs was updated. The major updates are that the Service Bus labs environment now uses v2 of the Access Control Service and topics/queues have been created. This pushes the number of queueing solutions on Azure to 3:
* Queue Storage
* Message Buffer
* Queues
The main difference between the types of storage relates to size and usage patterns. Queue storage allows for messages up to 8 KB in size and is primarily intended for applications running on Azure. The service only accepts one type of credentials, and you probably don’t want to share those.
The Message Buffer stores messages of up to 60KB for about a minute. It is great for volatile queues as a short lived rendezvous point for exchanging messages. This service lives on the Service Bus and allows for authentication with the Access Control Service.
The Queues implementation in the Service Bus allows for larger messages (up to 256 KB) which can last for a longer period of time. Interacting with the queue feature is pretty simple. Go to the https://portal.appfabriclabs.com page and allocate a Service Bus namespace. The ‘Hello, World’ for the queue looks like this:
static void Main(string[] args) { var sbNamespace = "your namespace"; var credential = TransportClientCredentialBase.
CreateSharedSecretCredential("owner", "[your key]"); var uri = ServiceBusEnvironment.CreateServiceUri("https", sbNamespace,
string.Empty); var client = new ServiceBusNamespaceClient(uri, credential); var messagingFactory = MessagingFactory.Create(ServiceBusEnvironment.CreateServiceUri("sb",
sbNamespace, string.Empty), credential); var queue = client.CreateQueue("demo"); var queueClient = messagingFactory.CreateQueueClient(queue); var sender = queueClient.CreateSender(); sender.Open(); sender.Send(BrokeredMessage.CreateMessage("test")); sender.Close(); var receiver = queueClient.CreateReceiver(); receiver.Open(); var message = receiver.Receive(); receiver.Close(); Console.WriteLine(message.GetBody<string>()); }
Integrating with the Camera in WP7
Posted by Scott Seely in Uncategorized on May 16, 2011
There has been a small white lie that many people tell when looking at whether or not a WP7 application can directly interact with the camera. The fib looks like this:
You can only access the camera through the CaptureCameraTask. Direct access is not allowed.
It didn’t seem right when I heard that, so I did some digging around, looking for ways to find out what is really contained in the phone. Some information is out there, and if you assemble the parts, you wind up with a better view into what managed code can do on the phone. I wrote a post earlier that showed what you need to do in order to make your development environment work better. As a result of that effort, you are going to be able to use the camera in your Windows Phone 7 applications today.
Adding live support for a phone is actually pretty easy. You just need to add some references to the right assemblies, add a little markup to your page, and then write a few lines of code.
References
Go ahead and create a WP7 XAML app. Once you do that, you need to add references to two assemblies that aren’t standard issue:
* Microsoft.Phone.InteropServices
* Microsoft.Phone.Media.Extended
Why two assemblies? The first one allows you to work with the second one-nothing more.
Add some markup to display the camera
To work with the camera, live, here is what you do:
1. Add a reference to the Microsoft.Phone.Media.Extended to the page you want to display the camera output to. For example, add the following to the PhoneApplicationPage element:
xmlns:media="clr-namespace:Microsoft.Phone;assembly=Microsoft.Phone.Media.Extended"2. With that in place, you can then put a CameraVisualizer on to your page. A CameraVisualizer displays the content of a camera on to a surface.
<media:CameraVisualizer Name="cameraVisualizer" Visibility="Visible"Margin="64,4,99,26" Height="426" Width="593" />Hook up the Camera to the Page
In your page’s code behind, add a Microsoft.Phone.PhotoCamera and attach it to the CameraVisualizer. You do that by calling SetSource on the visualizer. The code looks like this:
cameraVisualizer.SetSource(_camera);
Doing something with the Camera
From there, you can access methods telling you what is going on with the camera:
* ShutterPressed: Fires when someone presses the camera button.
* ImageSavedToDisk: Fires when the image you just took is saved to disk, passing along the path to the file.
* ThumbnailSavedToDisk: Fires when the thumbnail is saved. This one also has the image path.
When the shutter is pressed, you still need to tell the camera to take the picture. To do this, fire the CaptureImage method on the PhotoCamera instance. You can also do some cool things like set the flash setting, zoom level, and auto focus.
There are a few gotchas with the camera that do make it difficult to work with and show why it wasn’t available to all of us when the phone launched. First off, any time you use the control just a little bit ‘incorrectly’, you will see a COM exception. Second, any time that the visualizer goes off screen then back again, you need to detach any events, then hook them back up again or you will have a bad experience for your users. If you do not handle the pictures being taken in quick succession, you will have issues.
I invite you to play with the camera but be warned-it is a nasty beast to work with and you will spend quite a few cycles fixing weird little bugs. Microsoft never made a general release of this code because the code needed more QA before burning any cycles documenting the feature. They’ve already announced it will be in better shape for Mango, but if you want to use it now, I’ve given you enough rope. Have some fun (and don’t hang yourself)!!!
Thanks to Jeff Prosise for encouraging me to talk about this. We were chatting in late April at a conference when I was having some fun with a WP7 camera app I had written and he said he wanted to know how I did that.
Karmic Code Monkey 
You must be logged in to post a comment.