
Why We Chose API First Development at Our Startup - jqueryin
http://blog.pop.co/post/67465239611/why-we-chose-api-first-development
======
sbov
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's usually not easy though.

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.

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't use the interface keyword.

One of the oft maligned issues of c++ is the .h file. I rather like them
though. They're a constant reminder that "this is all you should know". It
becomes obvious when you add cruft onto it because you don't have that cruft
obscured by hundreds of lines of implementation. It's much more difficult to
notice it in languages where the implementation of a class or module is
present alongside its interface.

~~~
rpedela
Yep I agree. APIs are often much easier to test as well. Proper testing is
part of being disciplined.

------
girvo
In the past 6 months, at the urging of my friend Dave (sup!), who suggested
this style of development, it's all I've done, even for small personal
projects. I sort of take it further, eschewing frameworks somewhat, relying on
libraries around actual "Business Logic" to deliver stuff as needed to outside
clients.

It'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's
easier to do test driven development when things are nicely separated like
this!

It's basically SRP writ large, and something tells me it's another one of
those "ideas" 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...

~~~
macspoofing
Two problems:

1) Search engine indexing is broken with client-side rendering

2) Page takes longer to load, and so you will want some server-side rendering
to take place (even if to seed your initial models, so they don't have to call
back immediately).

~~~
napoleond
_1) Search engine indexing is broken with client-side rendering_

There is no rule stating that an API must be consumed client-side, and
obviously a great many can't be (depending on how auth is set up, etc). For
projects where SEO matters but where an API will also be useful (or if you've
just gotten into the habit of building user-facing bits around an API) you can
render everything server-side, or first loads server-side and subsequent loads
client-side. Airbnb's Rendr
([https://github.com/airbnb/rendr](https://github.com/airbnb/rendr)) is neat
for this, although there are a million other ways to do it.

If you combine this approach with something like CouchDB, your API can
basically just be your DB interface and you can focus on building the user-
facing bits.

EDIT: Sorry, everyone wrote the same thing at the same time :)

~~~
macspoofing
>There is no rule stating that an API must be consumed client-side, and
obviously a great many can't be

I wrote several responses to this but here's another one, if the server is
serving rendered HTML to the client, how is that API-first development?

I'm not disputing the merits of this approach, I'm just wondering what we're
arguing for here.

~~~
derefr
You develop a backend--a piece of software, running on your servers--with an
API as its interface. Then you develop a frontend--another piece of software,
running on your servers--that consumes that API, and has HTML as its
interface. These are two separate projects.

------
vcherubini
I did this when I first started writing REST APIs. It felt natural and the
"right" way to do it. However, it didn't scale well.

And I'm not talking about website scalability with traffic.

It eventually made development more difficult than it was worth. For example,
doing things like enabling/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.

I love REST APIs and I loved what they have done for the web, but I've changed
my mind over the last few months that this separation of design is always
necessary.

~~~
mason55
The other mistake that I've seen people make is to try to build their
application completely on top of a public API. Sometimes you want to do things
in your application that, either for security or scaling reasons, you don't
want someone consuming the public API to be able to do (bulk operations,
administrative functions, cross-account updates, etc).

You either need private API functions or you need to allow actions that aren't
triggered by an API call.

~~~
johns
Our public API is a front end for our other services with auth added on and
better guarantees against breaking. We don't depend on it directly for
anything public facing and I wouldn't suggest anyone completely rely the same
API they offer partners/openly to avoid getting into a tough spot with
managing changes.

------
jcampbell1
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.

I'd personally rather go back and extract the smallest possible functional
API, rather than build a massive API upfront. You don't really know where the
transaction boundaries are as you are developing, and it is easy to expose an
API that not really possible.

~~~
johns
The way we handle this (we have 18 internal services) is that processes
requiring transactions are formalized into a endpoint/resource. The actual
transaction becomes tangible (e.g. you can cancel them by DELETE-ing on the
resource) instead of just being documented. Only logic the client needs is the
data to kick off the process. Async or long-running processes get a little
tricker, but polling or webhook callbacks work fine for us.

------
jwingy
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.

~~~
jqueryin
You bring up a great point. I didn't cover mobile development specifically as
we hadn't had a use case for a mobile app yet as the site is full responsive.
I opted for more of a blanketed statement in the section on "Developer
Liberation" as to how the API covers all client bases equally well.

------
rubiquity
I love this development and it'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.

------
pyrrhotech
I thought all modern web/mobile apps were architected this way? Is this novel
information?

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

~~~
jqueryin
We use CORS, which unfortunately is more of a headache than it's worth and
lacks IE <10 support. Our backend proxies and handles session management via a
secure, hashed cookie helper library which maintains expirys among other
things. We take advantage of shared cookies on a global cookie domain .
There's some ugly handling for IE10 regarding CORS and how it handles cookies
which I won't get into. Authentication state is managed via the session, which
we actually query our backend for on page requests. It's a bit of overhead to
have to always be querying for the user/auth object to check login status, but
it's easily cacheable (and bustable).

------
macspoofing
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:

1) Search engines can't index your page properly. If you rely on this to drive
traffic, you'll have a problem

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't have to immediately call back.

~~~
kaolinite
1\. Not really true nowadays. Google can trawl Javascript sites. Other search
engines may be able to as well.

2\. Initial page load will be slightly higher (and subsequent pages will be
much faster) but I can't imagine it'll be too noticeable. People get away with
a lot - even on mobile - loading numerous JS libraries, tonnes of CSS, etc. As
long as you go easy in other regards, this shouldn't be a problem.

There's no reason that API driven design has to involve client-side rendering.
You can always consume your API on the backend and render on the server.

~~~
macspoofing
>There's no reason that API driven design has to involve client-side
rendering. You can always consume your API on the backend and render on the
server.

I'll give you that I suppose, though I understand it as a lightweight server,
and heavier client. On the other hand, splitting up your components into API
and page-rendering servers (in addition to your database, caching, messaging
servers and your reverse proxies and load-balancers) complicates your
deployment and maintenance and you pay for that - so it isn't quite the
panacea and now you really have to decide whether it makes sense to go down
that route, that early.

~~~
kaolinite
It's not really any more or less complicated than doing it on the client-side,
especially if you use something like Her
([https://github.com/remiprev/her](https://github.com/remiprev/her)). It's
definitely more complicated than just using a database though - whichever way
you do it. It's the other advantages that it brings that makes it potentially
worth doing.

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

~~~
iaskwhy
I use the following sources as standards:

\- Vinay Sahni's Best Practices for Designing a Pragmatic RESTful API:
[http://www.vinaysahni.com/best-practices-for-a-pragmatic-
res...](http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api)

\- HN discussion on Vinay's post:
[https://news.ycombinator.com/item?id=5819231](https://news.ycombinator.com/item?id=5819231)

\- Twitter's Error Codes & Responses: [https://dev.twitter.com/docs/error-
codes-responses](https://dev.twitter.com/docs/error-codes-responses)

~~~
johns
If I can throw my own in: [http://john-sheehan.com/blog/dont-build-the-best-
rest-api-bu...](http://john-sheehan.com/blog/dont-build-the-best-rest-api-
build-the-best-http-api)

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

------
X4
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?

Only found: [http://apiary.io/](http://apiary.io/) but it doesn't generate any
code.

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

~~~
johns
It's a lighter weight form of the same idea. SOA had a lot of great benefits
for its time. This revision of those ideas also has a lot of merit.

------
jemeshsu
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?

------
RobinUS2
Great initiative, I personally prefer to refer to this as "Eat your own sh*t".

------
Kiro
How do you handle authentication?

~~~
jqueryin
Vaguely answered here:
[https://news.ycombinator.com/item?id=6763221](https://news.ycombinator.com/item?id=6763221)

------
mkramlich
I'll just leave this here:

CLIFMO: CLI's First, Maybe Only

life will be better. trust me. it's a beautiful thing.

(Also a big fan of RDD or README Driven Development. I didn'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/hate relationship for TDD, in comparison --
it's a mixed bag, advantages and disadvantages, awesome and terrible,
depending -- but only pure love for RDD and CLIFMO.)

~~~
danudey
Our entire software deployment system across all of our servers is built on
systems built on systems built on a command-line tool I wrote in my first
month.

It's really useful because anything that you can do from our deployment panel
you can do by hand by logging into the server (and actually, even more stuff
which isn't exposed).

The one thing I haven't gotten around to doing is revamping the tool to
properly support JSON output for all commands. It might require a new logging
module to handle errors though…

~~~
mkramlich
nice! that sounds like CLIFMO to me. yeah it's amazing how much easier it
makes so many things. development-wise it yields so many freebies that pay off
later.

