WIP: User-facing API Spec

[bcwaldon]

Let's start talking about what we want out of a user-facing API.

[bcwaldon]

There's still a lot missing here, but hopefully this will help facilitate a discussion.

[bacongobbler]

https://github.com/rwl/go-endpoints hasn't been in development in 7 months. Does that matter? How about something more actively maintained like https://github.com/gorilla/mux?

I'd be happy to supply a proof of concept if I have the time.

[calavera]

Looking good. I'd leave implementation details out until we have something solid to implement.

[calavera]

I wonder if this should be called Watch, like in etcd.

[bacongobbler]

Well, depends on the implementation. Watching typically means that you're waiting for a specific event (singular), while subscribing typically means that you're just listening to events as they come in (plural).

From another perspective, if you're waiting for a game to come out, that's one event. If you're subscribed to a gamer's news feed that publishes release dates, then that's multiple events.

[calavera]

Do we want to translate this to something more restful? Maybe something like this?

• List jobs: GET /jobs
• Create job: POST /jobs
• Get job: GET /jobs/JOB_NAME
• Destroy job: DELETE /jobs/JOB_NAME
• Load job POST /jobs/JOB_NAME/load
• Unload job POST /jobs/JOB_NAME/unload
• Start job POST /jobs/JOB_NAME/start
• Stop job POST /jobs/JOB_NAME/stop

It would be also great to follow some of the hypermedia conventions. These are a couple of links about how the github api implements this:

https://developer.github.com/v3/#hypermedia
https://developer.github.com/v3/users/#get-a-single-user

[polvi]

One big thing to talk about with this: should the API directly expose the systemd/fleet directives, instead of exposing an API to push a unit to? The unit is the API, fundamentally, so writing a client would involve serializing/templating out a systemd unit, then posting it to the API. It feels like it should be more of a direct API call, like using a transient unit in systemd.

[lukebond]

Very glad to hear this is in the works, I could really use this.

From my perspective as a newcomer to CoreOS, in an API I basically want to do what fleetctl does, but over HTTP. I want to submit, list, start and stop units, and list machines. I also want to know when fleet learns about new machines and change of state in units. I expect to be submitting unit files rather than just a run command (if the latter is what @polvi had in mind when he mentioned transient systemd units?).

The API draft above seems to cover all of this. The only missing things I can think of:

• I don't see the equivalent of "list-machines" in the API. I see the machine up/down events of course, but one needs to get the initial list of machines for the events to be meaningful if the client wants to keep an up-to-date list.
• I'd want to have access to the logs somehow, too (i.e. fleetctl journal). Is this in scope? I would like to be about to tail recent logs and follow them, perhaps streaming the latter to a browser via a socket. I'm not sure if long-running HTTP is the best channel for that sort of thing...

Very excited about this turning up, very keen to get hold of it and test it when it does!

[jonboulle]

@lukebond: to touch on your last point, systemd ships with just such an HTTP service to provide access to to the journal. I also opened #355 just yesterday to raise the question of whether we might use this within fleet.

[lukebond]

good to know! thanks

[jonboulle]

@polvi can you expand a bit on what exactly you would see that looking like? What directives would it support?

[bcwaldon]

@jonboulle polvi and I talked offline. He was suggesting we offer a method of starting units like systemd-run, which wouldn't require a client actually provide a full unit file.

[jonboulle]

got it, and +1 to that - we should add fleetctl run and expose the equivalent through the API

[andrewreedy]

👍 fleet rest API would be really useful. I would be into helping with a frontend for it.

[bcwaldon]

I spent the last few hours working on an actual spec: #534