IMHOs on the API

Matt Wagner matt.wagner at redhat.com
Wed Jan 16 21:59:06 UTC 2013


On Wed, Jan 16, 2013 at 03:09:13PM +0100, Martin Povolny wrote:
> While I am at the writing mood today I would like to say a couple of
> things to the API. All these are IMHOs so let's pretend there's a IMHO
> in front of each point.
> 
> i) the API implementation should start with what the consumer needs or
> wants
> 
> 1) the client would want to start with launching things (deployment)
> 2) next the client would want to check if the thing he wanted to run
> actually runs
> 3) next the client may want something else like list all the stuff he
> has

I agree with all of this, expect that I would note that in many (?)
cases, a user may want to build a new image before then creating a
deployment.

In the past, we didn't support launching over the API, which was
regrettable since it was obviously something many users would want to
do. It sounds like this is in progress already, though, fortunately.

> ii) the API needs a client to check it's actually good
> 
> I already wrote in a different thread that freezing the API before
> verifying that it's actually usable by having at least one client is not
> a good idea. In our project probably the first client is the CLI.

I haven't worked enough with the API to have an informed opinion here,
but this makes a lot of sense to me.

> iii) the API structure need not copy the internal structure of the
> project (being it the models or the controllers)
> 
> Actually the API should hide the implementation details as much as
> possible and it should be structured in a way that is logical from the
> consumer point of view.
> 
> iv) from the above it's obvious that having the API in the same
> controllers that serve the WUI might not always be the best way to do
> not only in terms of spaghetti popularity.

This is where I start to disagree a bit.

The API doesn't need to expose all the nitty-gritty implementation
details we have, but having the same controllers and methods service
both the UI and the API is a common Rails pattern and usually results in
cleaner, DRYer code. The actions should be doing the same thing
regardless of whether the consumer is a web browser or an API client,
with the only difference being whether we respond with HTML or XML/JSON.

For a long time, we ended up with separate controllers dealing with
images for the API and the UI. It turned into a big mess, with a lot of
duplication. Worse than duplicate code, we started getting divergent
duplicate code, where someone would fix something in the UI controller
but not the API, and things just turned into a hard-to-maintain mess.

Of course, like you wrote in your email, this is all just IMHO.

-- Matt


More information about the aeolus-devel mailing list