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. Trying to make a systems-level claim based on one component, or even one layer, of that system simply doesn’t work.
15 Sep 2016
22 Apr 2016
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.
08 Oct 2015
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.
28 Sep 2015
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.
26 Aug 2015
[Warning: Potentially Inflammatory Topic]