Artifact uploads and downloads
The general usage of artifact uploads and downloads is documented in the user guide. This page documents the actual API flow for uploading or downloading an artifact and is only useful to developers implementing new Shaken Fist clients.
Artifact uploads normally require multiple HTTP requests in order to complete. This is because artifacts are often very large, and the REST API wants to allow you to continue an upload even if a single HTTP session fails or times out. This is implemented by creating an upload object, POSTing data to that object repeatedly, and then converting that upload object to an artifact.
Upload objects which have not have data posted to them in a long time (currently 24 hours) are automatically removed.
You create an upload by POST'ing to
/upload. This will create a new upload
object and return you a JSON representation of that object. The JSON includes
the UUID, node the upload is stored on, and when it was created.
Then repeatedly POST binary data to
/upload/...uuid.... This binary data is
blindly appended to your upload object. Do not encode the data with base64 or
similar. Each call will return the new size of the object.
If necessary, you can also truncate an upload object to a specified size, for
example if you are unsure that a POST operation completed correctly. You do this
by sending a POST to
Once your upload is complete, you convert it to an artifact by calling
/artifacts/upload/...name... to convert it to an artifact.
There is one final optimization to uploads, which is implemented in the python
API and command line clients. If before upload you calculate a sha512 of the
object to be uploaded, you can then search for that checksum with the
/blob_checksums/sha512/...hash... endpoint. If a blob is returned then you
don't need to actually upload and can instead pass that blob uuid (with a POST
blob_uuid) instead of an upload uuid to the
/artifacts/upload/...name... endpoint. See the swagger documentation for more
Artifact downloads are implemented as fetching the data for the desired blob. You
therefore must first lookup the versions for a given artifact and select a version
that you wish to download. You can then fetch the data for the relevant blob by
/blobs/...uuid.../data this call takes an optional query parameter of
offset, which specifies how many bytes into the blob to start returning data
from. This allows recommencing failed downloads.