docs/draft: API design document

docs/draft: API design document



https://code.launchpad.net/~rogpeppe/juju-core/212-api-doc/+merge/147919

(do not edit description out of merge proposal)

[rog, 2013-02-18 11:03:56]

Please take a look.

[jameinel, 2013-03-18 07:18:31]

LGTM

I have some comments, but I'd certainly much rather see the document landed
rather than just existing in a CL.

https://codereview.appspot.com/7314085/diff/2001/doc/draft/api.txt
File doc/draft/api.txt (right):

https://codereview.appspot.com/7314085/diff/2001/doc/draft/api.txt#newcode47
doc/draft/api.txt:47: in Go (and hopefully other languages too).
My immediate thought on this is to watch out for "potato programming" where you
end up getting a batch of objects to work on, and then do a round trip to update
each one.

So long as the API doesn't preclude getting to a point where you can do
efficient batch operations, starting with what you have seems fine.

https://codereview.appspot.com/7314085/diff/2001/doc/draft/api.txt#newcode241
doc/draft/api.txt:241: advantages in simplicity too.
You haven't quite defined what happens if a connection is lost. Is there an
implicit "Stop" request?

It does seem like adding a fair amount of overhead to get one step every time,
rather than allowing "Next" to encapsulate a bunch of changes at once. Though
maybe it does and I'm misunderstanding? (All of you Next responses are empty, so
it is hard to tell their structure.)


If doing "Next" would allow you to batch the response, then it actually sounds
like a win vs having the server push individual events.

https://codereview.appspot.com/7314085/diff/2001/doc/draft/api.txt#newcode256
doc/draft/api.txt:256: usually works - hopefully there's a way around it in
node.
"way around it in node" ?

I don't quite understand that bit.

https://codereview.appspot.com/7314085/diff/2001/doc/draft/api.txt#newcode291
doc/draft/api.txt:291: approach).
So the connection itself is authorized, not a token that you pass into requests?

Other services have enjoyed a lot of scalability by making them 'stateless'
(which IME just means the state gets passed into each request rather than there
actually being no state).

This makes it far easier if you ever needed to scale up to more than one node
serving the requests. (How well is one API client going to be able to handle
2000+ nodes with watchers? Is that even likely? I don't quite know how hook
triggers are sent out to clients, but it does seem like they would be polling
the provisioner.)

For example, 2000 socket connections is over the default 1024 limit of select().
Certainly 100k nodes is over the 65k limit of port numbers. (much less the
actual capacity of a single machine.)

Have you considered using a stateless service rather than state-ful connections?
It tends to be harder to write, but much easier to scale.

[thumper, 2013-03-19 01:41:34]

The draft directory inside doc was removed some time ago.

You may want to remerge trunk and move the api.txt file into the doc directory.

[rog, 2013-03-19 08:04:38]

Thanks a lot for the review.

https://codereview.appspot.com/7314085/diff/2001/doc/draft/api.txt
File doc/draft/api.txt (right):

https://codereview.appspot.com/7314085/diff/2001/doc/draft/api.txt#newcode47
doc/draft/api.txt:47: in Go (and hopefully other languages too).
On 2013/03/18 07:18:31, jameinel wrote:
> My immediate thought on this is to watch out for "potato programming" where
you
> end up getting a batch of objects to work on, and then do a round trip to
update
> each one.
> 
> So long as the API doesn't preclude getting to a point where you can do
> efficient batch operations, starting with what you have seems fine.

Thanks. I don't *think* it precludes anything.

https://codereview.appspot.com/7314085/diff/2001/doc/draft/api.txt#newcode241
doc/draft/api.txt:241: advantages in simplicity too.
On 2013/03/18 07:18:31, jameinel wrote:
> You haven't quite defined what happens if a connection is lost. Is there an
> implicit "Stop" request?
> 
> It does seem like adding a fair amount of overhead to get one step every time,
> rather than allowing "Next" to encapsulate a bunch of changes at once. Though
> maybe it does and I'm misunderstanding? (All of you Next responses are empty,
so
> it is hard to tell their structure.)

It does. For other kinds of watchers, Next can return a bunch of changes at
once. And even in the above example, the object may have changed multiple times
before Next is called, but Next will only return one change, which is kinda like
batching even though the only information is "something changed".

https://codereview.appspot.com/7314085/diff/2001/doc/draft/api.txt#newcode256
doc/draft/api.txt:256: usually works - hopefully there's a way around it in
node.
On 2013/03/18 07:18:31, jameinel wrote:
> "way around it in node" ?
> 
> I don't quite understand that bit.

s/node/node.js/

https://codereview.appspot.com/7314085/diff/2001/doc/draft/api.txt#newcode291
doc/draft/api.txt:291: approach).
On 2013/03/18 07:18:31, jameinel wrote:
> So the connection itself is authorized, not a token that you pass into
requests?

Yes, that's right.

> Other services have enjoyed a lot of scalability by making them 'stateless'
> (which IME just means the state gets passed into each request rather than
there
> actually being no state).

We did consider this, but for the time being anyway, decided that
a stateful connection would be more efficient, particularly as we
are using the same interface for agents. In time, we may want to
have a "stateless" (and possibly RESTful) API too.

> This makes it far easier if you ever needed to scale up to more than one node
> serving the requests. (How well is one API client going to be able to handle
> 2000+ nodes with watchers? Is that even likely? I don't quite know how hook
> triggers are sent out to clients, but it does seem like they would be polling
> the provisioner.)

Triggers are sent out to clients by replying to their Next requests.
I think there shouldn't be a problem running multiple API servers - the
main issue that I see is that if the server a client is talking to goes
down, the client will pull all the data from scratch when it reconnects,
because one server has no idea about the per-client state maintained by another.

> For example, 2000 socket connections is over the default 1024 limit of
select().

We use epoll, not select. A quick peruse of the documentation finds "the default
value for max_user_watches is 1/25 (4%) of the available low memory, divided by
the registration cost in bytes" - if there was 50MB free, that would give us
>130000 watches, which seems ok.

> Certainly 100k nodes is over the 65k limit of port numbers. (much less the
> actual capacity of a single machine.)

Yes, this is definitely an issue with any websocket-based system.
We will have to deal with it- we should be
able to add more API servers as necessary, however.

[rog, 2013-03-22 16:46:43]

*** Submitted:

docs/draft: API design document

R=jameinel, thumper
CC=
https://codereview.appspot.com/7314085