• 07 Oct 2016

    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. Rather, REST describes (in the form of constraints) the properties of the World Wide Web.

  • 16 Sep 2016

    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:

  • 15 Sep 2016

    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. Trying to make a systems-level claim based on one component, or even one layer, of that system simply doesn’t work.

  • 22 Apr 2016

    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.