<story><title>Designing a Pragmatic RESTful API</title><url>http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api?hn</url></story><parent_chain></parent_chain><comment><author>buro9</author><text>We&apos;ve built a first version of an API that we have in testing at the moment, and it follows a lot of the things laid out in an ebook✝ and in the linked article.&lt;p&gt;The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should.&lt;p&gt;I&apos;ve built a couple of very pure REST APIs in the past, but had a lot of developers pushing back and demanding something simpler. To not use media types so precisely, to be more accepting of what data is sent, to provide meta-data along with the resource (most seem to prefer an envelope), to prefer composite resources over very decoupled interfaces, etc.&lt;p&gt;This time, I haven&apos;t even tried to build a pure REST API. This time I&apos;ve just mixed together the bits that developers I&apos;ve spoken to liked and prefer. Adjusting as I went depending on how it was received.&lt;p&gt;&lt;a href=&quot;http://microcosm-cc.github.io/&quot; rel=&quot;nofollow&quot;&gt;http://microcosm-cc.github.io/&lt;/a&gt;&lt;p&gt;That&apos;s the docs for it, and we get the arguments out the way right at the beginning. All we&apos;re trying to do is build an API that helps developers get their task done. We&apos;re not done, and I know it&apos;s not pure anything... but the feedback we&apos;re getting is far more positive than any pure REST API I&apos;ve ever built.&lt;p&gt;✝ If you are willing to give out a fake email address then this free eBook is a great resource and has a lot of sane information presented clearly:
&lt;a href=&quot;http://pages.apigee.com/web-api-design-ebook.html&quot; rel=&quot;nofollow&quot;&gt;http://pages.apigee.com/web-api-design-ebook.html&lt;/a&gt;</text></comment>
<story><title>Designing a Pragmatic RESTful API</title><url>http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api?hn</url></story><parent_chain></parent_chain><comment><author>peterwwillis</author><text>This is a well-written and informative article, kudos.&lt;p&gt;That said, it reminds me how fucking overcomplicated REST HTTP API is for 99% of uses. As an API user, all I want is to call a function on a server, pass it some arguments and get a result. I want it to be dead simple, and REST is probably the opposite of that.&lt;p&gt;Finally, it also occurs to me that most API calls may call one function which returns lots of data that I don&apos;t need. Specifying the data types and field names I want in the query would simplify parsing and potentially reduce bandwidth use (if you&apos;ve ever seen an API call that returns a user&apos;s profile when all you wanted was their last login timestamp, you know what I mean). &lt;i&gt;edit&lt;/i&gt; Whoops, didn&apos;t see he mentioned the field limiter... why don&apos;t more people do that?</text></comment>