Design and Architecture is so much more than "X"

I saw this video after flopping around twitter last night (side note: anyone remember the days when you could easily reach the end of the internet? Now I can't even get through my daily twitter updates).

Private Library from A Space In Time on Vimeo.

I know nothing about the architect, Andrew Berman other than he gets design. He was commissioned to do X but as any great architect would, he considered Y and Z.

For instance he used copper in the external walls because he knew it would change over time just as the author he was designing the space for would. He knew the environment would not be static and considered seasons and light...

The things we do go so much further than some specification doc, or measurements. Do we consider the organic nature of software and the people who use it? As software developers are we considering Y and Z?

Innovating on Outreach - Milestone Church

They say you shouldn't judge a book by it's cover - but how do you do that as a new attendee to a church, or an un-churched person walking into their first "church" experience. I mean honestly, what else do they have other than their first reaction?

I had the pleasure of meeting Chris Sigler through the Fellowship One REST API beta that we have going on right now.

He's a super cool guy who proves that tech innovators are more and more becoming part of the standard fair of our local church. It's what our churches need - for far too long now we have had a light grip on IT / Web Dev in the Church Sphere. Church is the one place where innovation through the tools of technology should be pouring from the walls thanks to the forward thinking of their exec staff and Worlds of Wow.

Milestone is all about outreach and connecting with people. In my brief meeting with Chris and having a look around his church, you could tell that they are a "meet me where I" am kind of church. More photos on my photo stream.

They have a play scape for the kiddos right in the lobby, public WiFi for the parents, seating for connecting with others, etc... The whole place seems to be built around connecting with others.

Churches like Milestone, The Met, Fellowship Church, LifeChurch.tv, and others get the proverbial "it."

I gave a talk at DC09 on "Reaching the Unreachable" where I stated that:
context + timeliness = successful outreach

A big part of the reaching the unreachable is that most times people can only hear when they can relate and when they are in a trusted environment. Too often we are found walking into our churches with Teflon smiles and filtered voices. The reality is that virtual people are more "real" than real people, and real people are more "virtual" than their virtual counterparts. You could learn more about a person by studying them for 5 minutes in the social sphere than you can by seeing them for 1.5 hours on the weekend.

Let's get real with the people where they are like Jesus did. No doubt you're already on Facebook, twitter, MySpace, or any other social pipe - so use it for ministry and outreach, be innovative and throw some paint on the walls, get an access point and a $30 public pipe to the internet for the people who walk into your doors and for those who are standing at the online doors knocking.

Engineer for Serendipity

The title of this post is a quote from Roy T. Fielding (he had a hand in creating the HTTP 1.1 spec in 1999, basically defined / put into words the architecture and behaviors of the internet as a hypermedia system – REST, and has done about a million other things).

The quote alludes to making your “thing” so that users accidentally find something fortunate. While I do not believe in chance, I do believe in the serendipitous nature of innovation. Because of Fielding and others like him and their "out of the box" thinking we have the internet and all of its wonder.

This video (posted via @digital_nomads) illustrates what happens when people think outside of the web browser or app window and use technologies established over 10 years ago to make people stand and clap. It seems the device in the video uses web based APIs to get data and use it in an unbelievably awesome way.

As you build applications, I challenge you to kick out the ladder and set it on fire, challenge the walls of your device – push against them, bring them down.

If we do our jobs as software developers and API Architects, consumers will find themselves in the middle of serendipity.

RESTful Thoughts - OAUTH implementation for the F1 RESTful API Part 1

We took some time with this implementation and really did some soul searching on Authentication / Authorization mechanisms for the new Fellowship One API. The past few APIs that we've released used credential based authentication ( + signed keys for Payment Gateway) which was appropriate considering the intended usage.

With the RESTful API we know that churches, 3rd parties, vendors, volunteers, and the like will be consuming the API's secure resources - so we chose OAUTH.

The OAUTH features enable all of those consumers to create web sites or applications (consumers) that can access resources available via Fellowship One (Service Provider) securely, and without having to store or gather user credentials.

The benefits of our implementation of OAUTH are:

• Both the church and user will be able to protect / authorize access to their resources
• Resources will only be available to applications that both the church and users of that church has access to (configurable)
• The Consumer will never have access to login information or credentials - so the login is totally owned by the service provider

All requests for resources (excluding tokens and login) must have a Consumer Key, Access Token, and signature.

Roles of our implementation of OAUTH are:

• Service Provider: Fellowship One RESTful API - A web application (API) that allows access via OAuth.
• Consumer: 3rd party / church / Individual - A website or application that uses OAuth to access the Service Provider on behalf of the User.
• User: Portal User, User, Weblink User - An individual who has an account with the Service Provider.

OAUTH Parameter information (from the protocol documents):

• Consumer Key: A value used by the Consumer to identify itself to the Service Provider.
• Consumer Secret: A secret used by the Consumer to establish ownership of the Consumer Key.
• Request Token: A value used by the Consumer to obtain authorization from the User, and exchanged for an Access Token.
• Access Token: A value used by the Consumer to gain access to the Protected Resources on behalf of the User, instead of using the User’s Service Provider credentials.
• Token Secret: A secret used by the Consumer to establish ownership of a given Token.
• OAuth Protocol Parameters: Parameters with names beginning with oauth_.

Brief overview of the F1 OAUTH process (assuming all valid credentials and authority):

• The Consumer application will use a consumer key and secret to sign all URIs so that the F1 API will be able to verify the consumers identity and credentials.
• The Consumer application first requests a "Request Token" to use when the Users access the login pages -> The Service provider grants the request token.
• The Consumer application will direct the User to the Service Provider to obtain User Authorization
• The Service Provider will obtain authorization from the User and direct the User back to the Consumer
• The Consumer application will then request an Access Token -> The Service provider grants the request token and marks the "Content-Location" header with a URI to the User information.
• The Consumer application will use the Access Token to access Protected Resources

The process defined above requires accessing the following URIs:

Request token URI:
http://{churchcode}.{domain}/{version}/Tokens/RequestToken [POST]

Login URIs:
Portal Users http://{churchcode}.{domain}/{version}/PortalUser/Login [GET]
Weblink Users http://{churchcode}.{domain}/{version}/WeblinkUser/Login [GET]
Groups Users http://{churchcode}.{domain}/{version}/User/Login [GET]

Access Token URI:
http://{churchcode}.{domain}/{version}/Tokens/AccessToken [POST]

RESTful Thoughts - Planned HTTP Headers for the upcoming RESTful API

Here is the HTTP Header map for the upcoming Fellowship One RESTful API. Please comment / ask questions / make suggestions.

Just like the response codes, many decisions made for this map came from RFC2616, Fielding's dissertation, and analysis of several dozen RESTful or REST "like" APIs currently on the programmable web.


Request Headers

Accept : type/subtype

Example - Accept : application/xml (Available types and sub types: application/xml, application/json)

Notes - Defaults to application/xml if one is not passed in, and when a user sends application/* the resulting content sub type will be XML. Multiple types/sub types can be sent in but as per the specification the first match in degree of specificity will be the first used.
i.e. if user sends in: application/*, application/xml, */* the order would be as follows:
1) application/xml
2) application/*
3) */*

If an invalid value is passed in via Accept header the response will result in a 415 Unsupported Media Type

Accept-Charset : charset

Example - Accept-Charset: utf-8

Notes - Accept-Charset will not be used and will always default to utf-8

Accept-Encoding : encoding

Example - Accept-Encoding : deflate, compress, gzip

Notes - If none is sent in then the API will default to no compression.
If an invalid value is passed in via Accept-Encoding header the response will result in a 406 Not acceptable

Authorization : credentials

Example - Authorization : Oauth realm=http://api.f1.com

Notes - This is where the OAUTH credentials will go

Date : HTTP-date

Example - Date: Thu, 29 Jan 2009 15:28:25 GMT

Notes - Optional, most commonly passed in with PUTs and POSTs

User-Agent : product/comment

Example - User-Agent : MyChurchSite/v123.x

Notes - Used to identify the HTTP library or client library that was used to consume the API

Response Headers

Allow : method

Example - Allow: GET, HEAD, PUT

Notes - An Allow header field MUST be present in a 405 (Method Not Allowed) response.

Content-Encoding : content-coding

Example - Content-Encoding : gzip

Notes - This will tell the client what type of compression was used on the resource

Content-Length : DIGIT

Example - Content-Length : 1254

Notes - Sent back with each request. Will possibly be available via HEAD requests

Content-Location : absoluteURI | relativeURI

Example - Content-Location : http://api.f1.com/API/People/22114944

Notes - Sent back with each GET request

Content-Type : media-type

Example - Content-Type : application/xml, utf-8

Notes - Details the type of content being returned to the client

Date : HTTP-date

Example - Date: Thu, 29 Jan 2009 15:28:25 GMT

Notes - Will be returned with every response, possibly excluding responses returning status codes of 500

Location : absoluteURI

Example - Location: http://api.f1.com/API/People/22114944

Notes - Applies to 201 and 301 only

WWW-Authenticate : challenge

Example - WWW-Authenticate : Oauth realm: http://api.f1.com

Notes - The URI will change per environment, per version

Notes on caching
All headers having to do with caching are still being implemented.

This HTTP header map is subject to change, however, in the current build of the API these rules exist as defined.

RESTful Thoughts - Planned response status codes for the upcoming RESTful API

In the interest of honoring standards here is the response status code map for the upcoming Fellowship One RESTful API. Please comment / ask questions / make suggestions.

Many decisions made for this map came from RFC2616, Fielding's dissertation, and analysis of several dozen RESTful or REST "like" APIs currently on the programmable web.

200 - ok (GETs, PUTs, and DELETEs)

Entity body - The resource

Example - GET People/1

201 - Resource created (POST)

Response Header - Location will contain the canonical URI

Entity body - the new resource

Example - POST People

301 - Moved Permanently

Response Header - Location will contain the new permanent canonical URI

Entity body - will be empty

Example - GET People/1 has been merged and no longer exists the new URI is People/1

400 - Bad Request: There is an error on the client side.

Response Header - No modification

Entity body - Send back a message on why the request was bad

Example - Malformed XML fails to serialize eon the server

401 - Unauthorized

Response Header - WWW-Authenticate : OAUTH and the challenge or required parameter

Entity body - Optionally, a doc describing the failure

Example - missing OAUTH credentials

403 - Forbidden - Failed authorization

Response Header - No modification

Entity body - explanation of why authorization failed

Example - OAUTH credentials were good, however, the token used for the request was not valid or user associated with the token does not have rights to the resource

404 - Not Found: When a client requests a URI that does not map to a resource on the server

Response Header - No modification

Entity body - will be empty

Example - GET People/1 does not exist, optionally a 410 may be used (see below)

405 - Method not allowed

Response Header - Allow: GET, POST - list the HTTP methods the resource supports

Entity body - will be empty

Example - POST People/1/Status <- an attempt to create a status when only GET is available

409 - Conflict: Client tried to put the servers resource in an impossible or inconsistent state

Response Header - Allow: GET, POST - list the HTTP methods the resource supports

Entity body - will be empty

Example - POST People/1/Status <- an attempt to create a status when only GET is available

410 - Gone: server knew there used to be a resource but it's gone now

Response Header - No modification

Entity body - explanation of conflicts

Example - PUT People/1 modifying "Weblink" credentials for People/1 that are already used by People/2

415 - Unsupported Media Type

Response Header - Code detailed supported media types for the given resource

Entity body - will be empty

Example - Resource only supports XML and JSON, but the client sends application/atom+xm

500 - Internal Server Error

Response Header - No modification

Entity body - will be empty

Example - The server encountered an unexpected condition which prevented it from fulfilling the request.

This response status code map is subject to change, however, in the current build of the API these rules exist as defined above.

Web dev - Back to the basics

Some of the most important aspects of creating web based API, or any web based application is messaging and behavior - user experience. Back in 1999 when the HTTP 1.1 protocol was defined and the HTML 4.0.1 spec was released the web began to get more lively.

People stopped using World Wide Web and AOL interchangeably and we all jumped in our web dev boots, and rushed to inflate the bubble that would burst only a few years later.

courtesy of: Dana Summers, The Orlando Sentinel

Ironically, with web usage up, daily life being immersed in web jargon, popups, ads, and UI travesties, standards seemed to become less important.

All of those RFCs written by Fielding and gang seemed to melt away and get replaced by blinking text and Internet Explorer 5.0. I know I am generalizing; there we're a few outliers that challenged the norm and chose standards like the Netscape, but it seemed for the most part we used the web to showcase our madd skillz with using bloated back ground images and auto playing midi files for each "lucky" visitor <- I was, indeed, one of the worst violators of midi web attacks. The rule breaking was not limited to UI though, many services misused protocols and redefined established patterns in order to fit the web into antiquated business models.

Maybe that history muddied the standards / protocol waters; I mean shouldn't every web developer / architect know how HTTP works? What if we as developers simply relied on a tool or framework like visual studio and .NET to handle all of that crazy HTTP stuff for us? Would you hire a "Web developer" that did not know what the difference between a GET and a POST was?

I was blessed to have had an opportunity to go to MSDN Dev Con yesterday. I was sitting in a session ASP .NET 4.0 road map given by Ben Scheirman. He said something during his presentation that struck a web cord with me, I'll paraphrase:

With ASP .NET MVC, Microsoft looked at other MVC based frameworks and put together a solid tool to let developers do what they want to do and let the .net framework help and not get in the way.

For so long now, many .net developers have been using tools to write their HTML and CSS for them. We have ignored the basics. I chose ASP .NET MVC because of the flexibility of the pattern (not because of the Microsoft technology) and I truly enjoy the fact that standards and practices whet into the making of it (begin soapbox - I do not like how you can decorate your actions with HTTP verbs - would I ever do a post on a show? If so, wouldn't I be breaking the convention of the pattern? - end soapbox).

I find myself having to go back to things like RFC2616, Fielding's dissertation (when working on the RESTful API), and even the HTML spec daily. I find those tools far more valuable than an IDE or a managed framework.