Swagger Ain't REST - is that OK?

If you’ve spent much time with me, you’ve undoubtedly heard me ramble on at length about linked data. And in those conversations, you’ve likely heard me say something to the effect of “linked data is REST”. However, I haven’t really spent much time talking about REST by itself - especially considering the amount of importance heaped on it by proponents of the “API Economy”. I’ve focused my attentions elsewhere primarily because as an architectural style, REST isn’t something that a team can just go and implement.

Goodbye Jekyll, Hello Metalsmith!

While I love the simplicity of Jekyll for generating static Web sites from markup documents, the fact that Jekyll is built on Ruby and its respective ecosystem has been giving me increasing frustration. The reason for the growing frustration comes down to this: A Ruby app is a bait and switch. Looking at the code itself, the language has an apparent elegance to it (I mean, if you factor out all of that OO nonsense).

There is No REST API

I’ve spent some time talking with my teams recently about REST from the perspective of an API, and also how APIs built through the lens of technologies like Swagger go against some of the most important principles of REST. As I’ve reflected more over conversations, there is one even more fundamental thing that tends to get lost in the conversation. And that is that REST doesn’t describe APIs. REST describes the architectural characteristics of an entire system, which includes all of the different components of that system.

A Question on API Design and Documentation

One of the projects that my team owns is the Concur Developer Center. Among other information, it houses the documentation for Concur’s Web APIs. The documentation for the more recent API versions uses Swagger and until recently was generated by reflecting over the .NET API code. There were a bunch of problems that resulted from this approach as I’ll describe in a second. But there’s also some interesting trade-offs about the kind of APIs you get by focusing on service contracts as your primary design artifact.

Growing Pains

If there’s one thing that I want for the 10 of you that read this blog (hi dad!), it’s that you know that I want to be as transparent as humanly possible with you - about both the successes and failures. I started with Concur as a development manager about a year ago and was promoted to director a few months ago. This is post is an update of what’s gone well, what hasn’t gone as well, and some areas where I’m not really sure whether what I’m observing is good or bad.

Configuring Akamai with S3 Static Websites

For the next generation of the Concur Developer Center, we decided to break away from the standard enterprise, CMS-backed Web site and do what has become pretty common practice in the open source world for Web sites: we generated a completely static HTML Web site from markdown files using Jekyll. Even with a static Web site, we want to do as much as possible to reduce latency - especially for mobile devices and parts of the world that may not have tons of bandwith to spare (or just those that happen to be located far from Amazon’s Oregon data center).

The Role of QA in Cloud DevOps

[Warning: Potentially Inflammatory Topic] Today was a bit of a rough day for me in that I did something that is generally a bit aggressive for me. I abruptly closed an issue that was opened by one of our QA folks, thereby halting the discussion. The issue wasn’t really a bug - even though it was opened as one. It was more of a questioning of the API’s resource naming strategy (more specifically, a question around the use of singular and plural nouns for a specific path segment).

I lost a friend today

I have a million and one things that I should be doing right now. There’s code that needs to be reviewed, more code that needs to be written, customer calls to prepare for, expense reports to approve (and submit). I’m not doing any of those things right now. None of that feels all that important. I learned today that my friend and former colleague, Thomas Remkus, just lost his fight with cancer.

On API Gateways

Do you or your company build Web APIs and, if so, do you use an API gateway to broker traffic between your customers and your products? In this post, I want to tell you a little about our experience with this class of products and add a little of my opinion, but if you’re using an API gateway, I want to hear about your experience - the good and the bad.

9 Months In - Reflections on Teams and Agile

I’ve been a dev manager now for about 9 months and I have to say that I’m really enjoying this role. It’s not a job without frustrations, and I haven’t escaped the all of the frustrations that I had as a PM - particularly that of trying to balance writing code with “other duties as assigned.” However, when it’s all summed, I think that I’m a much better fit for operating on the engineering side of the house than I am at the business side.