REST Publish API

[tombentley]

For tools that want to publish modules to Herd we need an API, so that over HTTP(S) a tool can:

1. Obtain an upload URL (or equivalently an upload ID, but a URL would be better)
2. POST artifacts to this URL
3. Perform the publish step. If Herd's checks fail at this point it should explain why so the tool can give a sensible error message to the user.

We should also provide an Java/Ceylon API around this web API, to make it easy to write tools which use it.

[FroMage]

Something like:

OPTIONS /

Link: <https://herd.ceylon-lang.org/api/6/upload/new>; rel="http://modules.ceylon-lang.org/rel/upload-new", ...

POST https://herd.ceylon-lang.org/api/6/upload/new
...
CREATED
Location: https://herd.ceylon-lang.org/api/6/upload/76523
Link: <https://herd.ceylon-lang.org/api/6/upload/76523/publish>; rel="http://modules.ceylon-lang.org/rel/upload-publish", ...

I don't think we need a link/rel for DELETE for the same url, I think that's implied, like the POST method for the upload-new.

Then if you GET that upload you get a status:

<upload status="OK/WARNING/ERROR">
 <diagnostics>
  <diagnostic status="OK/WARNING/ERROR">
   Unknown file: foo.txt
  </diagnostic>
 </diagnostics>
 <modules>
  <module>
   <name>com.foo</name>
   <version>2.3</version>
   <diagnostics>
    <diagnostic status="OK/WARNING/ERROR">
     Missing docs
    </diagnostic>
   </diagnostics>
  </module>
 </modules>
</upload>

And same would be returned in case of error to upload-publish, while on success it would include links to the published modules.

Somewhere we have to stick links to the upload UI too.

[FroMage]

Somewhere we have to stick links to the upload UI too.

The UI, and the upload repo URL that the tools can use to publish things to.

[FroMage]

We can also have the following CLI plugins:

$ ceylon herd new-upload
New upload at: https://...
# Saves current upload ID in `.ceylon/config`, yells if there was already one
$ ceylon herd publish
# Uses current upload ID in `.ceylon/config`, yells if there was none
$ ceylon herd delete-upload
# Uses current upload ID in `.ceylon/config`, yells if there was none
$ ceylon herd reset-upload
# Uses current upload ID in `.ceylon/config`, yells if there was none
$ ceylon herd upload module/version # copies stuff there
# Uses current upload ID in `.ceylon/config`, or creates a new one and remembers it
$ ceylon herd publish module/version #copies stuff there and publishes it
# Uses current upload ID in `.ceylon/config`, or creates a new one and remembers it

[FroMage]

We also need a reset option:

POST https://herd.ceylon-lang.org/api/6/upload/new
...
CREATED
Location: https://herd.ceylon-lang.org/api/6/upload/76523
Link: <https://herd.ceylon-lang.org/api/6/upload/76523/reset>; rel="http://modules.ceylon-lang.org/rel/upload-reset", ...

Again, implied POST