API
This page describes a JSON-based API for MediaGoblin. It is a WORK IN PROGRESS at the moment while it is being drafted before it gets implemented. Currently it only includes a submission API, based on a specific scenario which might not work in general for MediaGoblin but can be used as a springboard for further API improvements and specifications.
Scenario
A MediaGoblin server (MGS) is used for media storage/repository on behalf of a few other servers, called user servers (US) . A user of one US submits a multimedia file. The file is sent to the MGS and categorized on the US in some server specific way. All future use of the multimedia file on the US is processed by the MGS.
The collection of multimedia files from all of the US's is accessible through the MGS interface and through specific categorizations on each US via API or direct links to the content on the MGS.
Submission
For submission files are sent directly to the MGS for processing. Each US has to claim the uploaded multimedia file to start processing. The process is as follows:
- User fills in a form on a US. The form is in fact based up of two forms
- One for categorization on the US
- One is a file form for the MGS
- File is sent to the MGS with a unique name
- The name distinction should be designed to ensure uniqueness (perhaps uuid?)
- US saves a pending object with the categorization
- US claims the file through the unique name via an API which start the processing of the file
- The MGS processes the file as usual
- When the MGS has finished processing it notifies the US through a special callback url provided that the processing is finished and the file is available in the public store through a specific url
- US moves the object from a pending state to a real object with direct links (or api specific information which might be designed later) to the MGS
File claim/start processing API
A proposed json-based api to claim a file uploaded to a MediaGoblin instance. When a file is claimed, the necessary variables are the unique filename, the callback url and the uploader (uses OStatus WebFinger id). The request can of course also contains other metadata and in this scenario we add Creative Commons metadata like original author and license.
The following is the JSON Schema for the file claim:
{
"name":"Claim",
"properties":
{
"filename":
{
"type":"string",
"description":"Unique, claimable filename of an uploaded file on the MediaGoblin server",
"required":true
},
"callback":
{
"type":"string",
"format":"url",
"description":"URL to call when processing is completed/failed for notification",
"required":true
},
"uploader":
{
"type":"string",
"format":"email",
"description":"Webfinger email address of the uploader for identification",
"required":true
},
"creativecommons":
{
"type":"object",
"required":false,
"properties":
{
"author":
{
"type":"string",
"description":"Original author of the work, used for attribution",
"required":true,
},
"license":
{
"type":"string",
"format":"url",
"description":"URL pointing to the Creative Commons license used",
"required":true,
}
}
}
}
}
An example of a Claim in JSON would be:
{
"filename":"b5d9f282-08ce-11e1-93a3-b32377194cc9.png",
"callback":"http://example.com/pending/b5d9f282-08ce-11e1-93a3-b32377194cc9/",
"uploader":"user@example.com",
"creativecommons":
{
"author":"Claude Monet",
"licence":"http://creativecommons.org/publicdomain/mark/1.0/"
}
}
Callback/finished processing API
The callback function of the US should read and accept MediaGoblin JSON objects according to the following proposed schema when sent to the callback url provided in the original claim:
{
"name":"Callback",
"properties":
{
"success":
{
"type":"boolean",
"description":"Boolean to indicate whether the processing of the file was successful or not",
"required":true
},
"message":
{
"type":"string",
"description":"Optional message used when processing was unsuccessful to explain the reason for the failure",
"required":false
},
"location":
{
"type":"array",
"required":true,
"description":"Array of locations for the processed file (or files, e.g. when video file is encoded into the three possible HTML5 video formats",
"items":
{
"type":"object",
"properties":
{
"mediatype":
{
"type":"string",
"description":"Optional string to categorize the file, e.g. ogv, webm",
"required":false,
},
"location":
{
"type":"string",
"format":"url",
"description":"URL of the file in the public store",
"required":true,
},
}
}
"mimetype":
{
"type":"string",
"description":"Mimetype of the file to allow receiver to categorize pending object",
"required":true
}
}
}
Possible design problems
- Requires a separate upload (or possibly a rewrite of the current upload) to enable file claims
- A secure and unique filename to be claimed is needed
- MediaGoblin is user based but who is the user when files are sent in by users on a specific site? Use OAuth/OpenID? Perhaps tie closely with OStatus federation.
- Need a service to remove old unclaimed files (and what would be the time window?)
- Mediatype needs a better definition in the API (what can be sent, e.g. webm or WebM etc.)