Why We Chose API First Development at Our Startup

I find the biggest win about API first development is it forces discipline upon you. I find I can get most of the benefits if I code in a disciplined fashion. It&#x27;s usually not easy though.<p>In many ways, I find API first development most useful in languages such as python, which lacks the idea of an interface. Similarly, I find interfaces not much more than yet another tool that forces discipline upon you.<p>It seems like as we develop these abstractions which increasingly force more discipline upon us we forget that classes and functions are supposed to be abstractions themselves. We are supposed to be relying on the interface of those classes and functions, not the actual implementations, even if the class itself doesn&#x27;t use the interface keyword.<p>One of the oft maligned issues of c++ is the .h file. I rather like them though. They&#x27;re a constant reminder that &quot;this is all you should know&quot;. It becomes obvious when you add cruft onto it because you don&#x27;t have that cruft obscured by hundreds of lines of implementation. It&#x27;s much more difficult to notice it in languages where the implementation of a class or module is present alongside its interface.

In the past 6 months, at the urging of my friend Dave (sup!), who suggested this style of development, it&#x27;s all I&#x27;ve done, even for small personal projects. I sort of take it further, eschewing frameworks somewhat, relying on libraries around actual &quot;Business Logic&quot; to deliver stuff as needed to outside clients.<p>It&#x27;s been an eye opener. Sometimes it requires a little more upfront thought, but I end up with a much more maintainable project at the end of it. TDD is your new best friend if you go down this road, and the best part is: it&#x27;s easier to do test driven development when things are nicely separated like this!<p>It&#x27;s basically SRP writ large, and something tells me it&#x27;s another one of those &quot;ideas&quot; that the grey-beards learned a long time ago that we are only re-learning now. Although REST does kick the crap out of SOAP...

I did this when I first started writing REST APIs. It felt natural and the &quot;right&quot; way to do it. However, it didn&#x27;t scale well.<p>And I&#x27;m not talking about website scalability with traffic.<p>It eventually made development more difficult than it was worth. For example, doing things like enabling&#x2F;disabling an object is a whole API call rather than a simple UPDATE statement. Either you have to set up an API endpoint to handle toggling the status of that object, or you have to send a whole (sparse) request just to flip a flag. Stuff like that can be tedious.<p>I love REST APIs and I loved what they have done for the web, but I&#x27;ve changed my mind over the last few months that this separation of design is always necessary.

REST APIs are nice, right up to the point you need a transaction... three things need to happen in the correct order, and all succeed or are rolled back. If the API is too granular, then you end up pushing this logic to the client, and that turns into a disaster.<p>I&#x27;d personally rather go back and extract the smallest possible functional API, rather than build a massive API upfront. You don&#x27;t really know where the transaction boundaries are as you are developing, and it is easy to expose an API that not really possible.

You missed another benefit towards API first development: it makes it much easier to get a head start on mobile development as you can reuse many of your endpoints for common operations.

I love this development and it&#x27;s something I fight to try to get places that I work to adopt. Building your service through the eyes of a client gives so much clarity about both the what and the how. It pairs really nicely with TDD as well. You also end up getting an API for free out of it and have an easy transition to Service Oriented Architecture if you so choose.

I thought all modern web&#x2F;mobile apps were architected this way? Is this novel information?

How do you handle authentication and sessions? Just curious on the approach you took.

This approach is very attractive to developers because it makes things so neat and tidy and perfect, but there are two problems that you quickly run into:<p>1) Search engines can&#x27;t index your page properly. If you rely on this to drive traffic, you&#x27;ll have a problem<p>2) Your page takes a longer load (even more noticeable on mobile), so you will inevitably move some work back to server, whether to render some or all parts of the page, or seed your initial models with current values so that they don&#x27;t have to immediately call back.

Are there some go to standards for API design that are followed?

A &quot;How We Developed POP.co Following the API Driven Development Approach&quot; would find a lot of people quite interested too, I think.

Perfect timing!! I was looking for it. Do you know any opensource or free tool that can generate the commented code + API Documentation required, from the API spec?<p>Only found: <a href="http://apiary.io/" rel="nofollow">http:&#x2F;&#x2F;apiary.io&#x2F;</a> but it doesn&#x27;t generate any code.

This merely sounds like they&#x27;re adhering to the buzzword of the year 2008 - SOA. I&#x27;m I wrong? (Not that there&#x27;s anything wrong in that, just nothing new)

I wonder if API first approach is suitable for all type of app. Is there anyone taking this approach for a CMS site, a eCommerce site or a stock trading site?

Great initiative, I personally prefer to refer to this as &quot;Eat your own sh*t&quot;.

How do you handle authentication?

I&#x27;ll just leave this here:<p>CLIFMO: CLI&#x27;s First, Maybe Only<p>life will be better. trust me. it&#x27;s a beautiful thing.<p>(Also a big fan of RDD or README Driven Development. I didn&#x27;t coin that term but I was doing it long before I finally heard somebody coin it. RDD and CLIFMO FTW. I have only a love&#x2F;hate relationship for TDD, in comparison -- it&#x27;s a mixed bag, advantages and disadvantages, awesome and terrible, depending -- but only pure love for RDD and CLIFMO.)