REST Resources

Posted on March 27, 2012 by Howard Dierking

I got a question recently about my recent Pluralsight REST Fundamentals course. Several times throughout the course, I say something to the effect of “for more on X, check out the references section at the end of the module”. The question was – where are the references. The short answer is that each module has a PDF of the slides used – and the last slide is for references. However, to save you the trouble of going through each of the PDFs to extract the references, I’ll just provide a consolidated list for the entire course here. Hope this is helpful whether or not you check out the course – though I would love to get your thoughts on that as well!

Posted in architecture, HTTP, Web, Web API | 5 Comments

An Afternoon with Sinatra and Heroku

Posted on March 7, 2012 by Howard Dierking

This is a quick summary of my experience today getting my first “hello world” Web API written in Sinatra and deployed to Heroku.  For those of you who are already experts, you’ll probably find lots of things I did wrong or could have done differently – please tell me or point me to resources.  I want to get better at this.  It was a great experience that left me wanting to do more of it…

Getting setup to develop my first Sinatra application on Heroku was basically a 2 step process.  First I needed to get a Ruby environment that I could run on Windows.  This was the first point of confusion because it seems like there are quite a few different options.  However, it seems like rubyinstaller.org has basically risen to the top (at least in terms of Google results).  Ruby installer is a single Windows MSI which installs Ruby, some initial gems, and a bunch of other stuff that I’m not sure about.  By install, as best I can tell, it lays files down on disk and adds entries to the path environment variable.  After installing, I can test my ruby files by simply running Ruby myfile.rb in mingw32.  The second thing that I installed via MSI was the Heroku toolbelt.  Again, I’m not sure what all this installation did (I suspect more files and path mods), but afterwards I can run commands such as heroku login.

First, here were the resources I followed to get setup on Heroku:

The quickstart took me through the process of signing up (which I had already done), installing the tools, logging in through the command line which would setup ssh keys if I didn’t already have them (I did, and that was a little problematic), and then it linked off to the platform specific getting started guide.

The getting started with Ruby guide walked me through the process of developing a hello world api in Sinatra, testing it locally and then deploying it to Heroku.  The first step was setting up the Heroku tools again, which I think may have installed Git again on my system.  Need to check that.  Writing my first Sinatra app was crazy easy – in fact, this was all it consisted of:

require ‘sinatra’

get ‘/’ do

“Hello, world”

end

Testing locally consisted of simply running ‘ruby -rubygems web.rb’.   The next part of the setup dealt with creating a gemfile (using Bundler?).  This part still seems a little too magical for me, but I went through the tutorial and created a gemfile declaring a single dependency on Sinatra.  The sample also had a dependency on a gem called thin, but I tried installing that gem a couple times and it failed because I didn’t have some kind of Ruby developer kit.  I’m not sure what that meant, but I can run and deploy without thin, so that’s what I did.  On a quick glance, it appears that thin is a Web server?

The next step was to create a procfile which from what I can tell instructs the runtime (Cedar, is the runtime that Heroku is using I believe) how to launch my application in production.  The template also mentioned Rack, and I’m not sure how that relates to the other stuff, but it wasn’t a blocker.

Now, I tried installing foreman because the getting started guide made it sound like by doing this, I could get a more realistic test of how my app would run in Heroku.  The problem was that I couldn’t get foreman to run on Windows, and a thread on github made it sound like foreman simply doesn’t run on Windows at all.  Looks like I may be buying a Mac in the not-too-distant future.  At any rate, not having foreman didn’t keep me from being able to deploy.

The final step was super easy once I resolved an SSH issue – though I think that this was because I’m already comfortable with Git.  I simply initialized a new Git repo in my working folder and then ran the following command:

heroku create –stack cedar

This caused heroku to do a bunch of provisioning stuff, including create a new remote repository – which it then kindly added to my local Git config.  This meant that deploying my app was simply:

git push heroku master

Initially, the remote Git repo hung up on me because I had created a new SSH public key on my laptop and it wasn’t the key that I originally configured with Heroku – a search, however, lead me to the right heroku command to add my SSH key:

heroku keys:add

After running this, I was able to push to heroku, and saw that heroku spun up a Web server and launched my app.  4 seconds later, I ran ‘heroku ps’ and saw that it had crashed.  This was because I initially got something wrong in my procfile – so I fixed it and simply updated/pushed my repo.  It then redeployed and worked beautifully (at least as far as cUrl is concerned).

In general, there are still some things I need to know better before I’ll feel good about everything I’m doing – there were a lot of terms thrown out there in my getting started experience, and I’m confident that I barely scratched the surface on all of them – specifically, I’m thinking of:

  • Sinatra
  • Bundler
  • Cedar
  • Rack
  • Thin
  • Foreman

And of course, I need to continue to get better at Ruby in general.  However, this was my first experience – and all in all, it was a good one.

Posted in Heroku, Ruby, Sinatra, Web, Web API | 2 Comments

Building an Async WCF Service in .NET 4.5

Posted on November 30, 2011 by Howard Dierking

In the .NET Framework 4.0 version of WCF, managing multiple asynchronous operations, for example in the form of WCF and HTTP request/response operations, is currently very complex regardless of whether you use the existing event or Begin/End asynchronous pattern. The amount of code needed to facilitate even simple coordination tasks is large and prone to bugs handling errors and timeouts. Yet there are some common communication oriented scenarios that require managing multiple outstanding asynchronous operations:

  1. Execute multiple async operations in parallel and continue when they are all done (either successfully, failed, or timed out).
  2. Execute sequence of async operations, stopping if one of the operations fails or times out.
  3. Nest multiple async operations (first do A, then take result and feed to B etc.).
  4. Combine async operations with timers for easy polling at regular intervals.

The task-based asynchronous programming model first introduced in the .NET Framework 4.0 provides a simple abstraction for the definition, coordination, and management of these operations. As such, providing a first-class asynchronous development experience using tasks should make the above scenarios much simpler to realize.

In order to create an asynchronous service operation, the service developer need only define a service operation that returns an instance of either Task or Task<T>. The decision on whether to return Task or Task<T> depends on whether or not the service operation returns a value. For operations which specify void, Task should be retuned. For service operations that return a value, Task<T> should be retuned.

For task-based methods, if the OperationContractAttribute specifies a name, the name will be used as is. If no name is specified on the OperationContractAttribute, the method name will be used. If the method name terminates with the string “Async”, “Async” will be truncated from the method name and the resulting string will be used as the operation name. This is to avoid having a method like “FooAsyncAsync” on the client after proxy code generation.

If a service like the one below is written, an InvalidOperationException will be thrown because the task-based method has the same name as the sync and async methods.  As a result, a service of the type below would not be supported. 

[ServiceContractAttribute(Namespace = "http://microsoft.samples")]
public interface ISampleService
{
    [OperationContractAttribute]
    string SampleMethod(string msg);

    [OperationContractAttribute(AsyncPattern = true)]
    IAsyncResult BeginSampleMethod(string msg, AsyncCallback callback, 
        object asyncState);

    string EndSampleMethod(IAsyncResult result);

    [OperationContractAttribute(Name = "SampleMethod")]
    Task<string> SampleMethodAsync(string msg);
}
view raw InvalidAsyncServiceContract.cs This Gist brought to you by GitHub.

The following illustrates use of a task-basd asynchronous service operation which in turns calls out asynchronously to 2 external services, waits for both services to return, then calculates and returns a value based on the return values of the 2 external services. 

public async Task<double> CalculateShippingSubtotalAsync(int productID, string postalCode)
{
    var productServiceProxy = new ProductServiceClient();
    var shippingServiceProxy = new ShippingServiceClient();

    var t = productServiceProxy.GetProductByIDAsync(productID);
    var t2 = shippingServiceProxy.GetShippingCostForPostalCodeAsync(postalCode);

    await Task.WhenAll(t, t2);

    return t.Result.UnitPrice + t2.Result;
}
view raw WCFNet45AsyncService.cs This Gist brought to you by GitHub.

This service operation leverages the Task.WhenAll combinator in order to wait for the completion of both asynchronous external service calls in a manner that does not block the thread of execution. The C# 5 async and await keywords are then used to return identify the service operation as asynchronous and define the operation which adds the product unit price and the shipping price as a continuation.

After proxy generation, calling the service looks boringly good:

paymentServiceClient.CalculateShippingSubtotal(productId, postalCode);

Posted in Async, WCF | 3 Comments

ScrumPig 2 Backlog Filter Syntax

Posted on October 24, 2011 by Howard Dierking

As I talked about at the end of my AppFabric TV interview, I use a tool called ScrumPig to manage my personal workflow (one day, I would love to try it out across an entire team, but baby steps).  Recently, ScrumPig 2 was released, and added a very handy new feature for something that was becoming more than just a slight annoyance for me.  To give you a better idea of what I’m talking about check out a snapshot of my backlog.

unfiltered_backlog

The problem here is all of the items with the green diamond.  These represent completed items – and as time progresses, they (hopefully) multiply in numbers.  And while looking at such a view should make me feel super-good about myself, instead it just creates a bunch of clutter that keeps me from clearly seeing the next things that I need to work on.  Fortunately, ScrumPig 2 added a rich search syntax – and while I’m not going to blog the entire help doc on the subject, the following excerpt enables me to easily see just want I’m interested in:

General Syntax

text Matches the item name
“text” Matches the item name
#number Matches the item number
+term Must match
-term Must not match

Tasks

<p> Matches the pending state
<i> Matches the in progress state
<c> Matches the completed state
<b> Matches the blocked state
<x> Matches the cut state

As such, by simply entering -<c> in the search box, I get a view of all backlog items that are not completed.

filtered_backlog

Posted in my setup | Leave a comment

Some More Thoughts On OAuth 2 Sample

Posted on October 24, 2011 by Howard Dierking

Recently, Pedro Félix sent me some questions on an internal mailing list regarding the recent sample I pushed out for integrating OAuth 2 into Web API (if you haven’t checked out Pedro’s blog, you should go and do that).  I thought they were really good questions/comments, so I wanted to share them here, along with my responses, and invite you into the conversation.  Some of the “Qs” are comments, but in the name of keeping the format simple, I’ve just broadly adopted the Q/A format.

Q

Regarding the “A Brief Disclaimer” section, OAuth’s primary goal is delegated *authorization* on resource access. IMHO, your scenario fits well into this goal. The key observation is that the *resource* under access control is the *user’s identity*. Instead of the user *pushing* its identity to the service (e.g. Basic authentication or a federation protocol such as SAML), the service *pulls* this identity (just a resource from the OAuth view point) from a trusted-third party (Facebook).

A

I agree that it fits – However, I don’t yet believe that treating an OAuth resource server role as an identity provider “fits well” for 2 main reasons:

  • It seems wasteful to establish an OAuth session (using “session” since an access token as valid – and as such must be stored on the authZ or resource server) so that it can be used just long enough to get a piece of identity information.  For that scenario, the push model of federated identity tokens seems like a better fit.
  • Because OAuth is really an authorization protocol, and because the major players like Facebook act as both the authZ server and the resource server role, every application that wants to have Facebook authenticate its users (each “relying party”) needs to register a pho Facebook application with its own app key and secret – or use a broker like ACS that does this for you and sends you an identity token.  Again, doable, but feels to me like a misuse of OAuth.

Q

I’m unable to fit this scenario into any of the typical OAuth use cases/profiles. Typically, the OAuth client

  1. is a webapp interacting with the user via a browser
  2. is an active client running on the user’s machine

In this scenario, the OAuth client is a web service, being accessed by a service client on the user’s machine:

A

The scenario is a modification of a standard OAuth server flow.  Web API is the OAuth client, Facebook is the AuthZ and resource server.  Web API fits into the definition of a confidential client here and as such, I’m using an auth code grant type.  Where this breaks off from the more typical OAuth flow (which would generally be a Web application) is in the fact that the UX is a single page, AJAX-driven app, so there’s an additional protocol (term used loosely) happening between the jQuery code and the Web API.

Q

IMHO, it would be better to start with simpler scenarios

  1. web api as a resource server, using an external authz server (e.g. AppFabric’s ACS)
  2. web api as an authz server, using various grant_type (password, client_credentials, saml,…)

A

I called those out at the bottom of the post and these are the scenarios that I’m working through now – For people unfamiliar with the world of federated identity, though, I would argue that they are not inherently simpler scenarios.

Q

On OAuthFacebookOpHandler, I don’t think that attaching the principal to the current thread is a good idea on this brave new world of asynchrony – the underlying thread may change several times. A better solution would

  1. Attach the principal to the current request message (the threads may change on a request, but the request message doesn’t)
  2. Return the principal as an http parameter, so that it can be used as an input parameter on downstream handlers and on operations

A

both good ideas – will update

Posted in OAuth, Web API | 3 Comments