Draft, 10/01/2010
InOut is a webservice for file handling and conversion. It is designed to make working with content easier for developers.
We hope you find the service to be easy-to-use, reliable and inexpensive. If you want to provide feedback to the InOut development team, please post a message over the Feedback link on every page of this documentation.
This document is for developers who are creating libraries to implement the InOut API. You can use the API documentation to learn how the http packets should look for particular requests.
Use of this document assumes you are familiar with the following topics:
This documentation provides a link at the sidebar of each page that enables you to enter feedback about this documentation. We strive to make this document as complete, error free, and easy to read as possible. You can help by giving us feedback. Thank you in advance!
This API defines a language and platform neutral protocol for clients to interact with InOut services. As a protocol, it is intended to be reasonably easy to implement in any language and on any platform.
The protocol operates primarily in terms of resources and operations on them. It is defined on top of the HTTP protocol, and uses the standard HTTP methods (GET, POST, PUT, DELETE, etc.) to retrieve and change server state.
The protocol defines "Profile" and "Conversion" resources. All operations consist of retrieving (GET), updating (PUT), creating (POST or PUT), or destroying (DELETE) these resources.
This protocol defines representations for each resource in the widely supported JSON [RFC4627] format.
Date and time values are represented as Unix Time, based on seconds since standard epoch of 1/1/1970.
All JSON responses are wrapped in a JSON response envelope which contains a boolean "ok" attribute signaling success and the result data itself.
{"ok": true, "result":
/* API call result. Depending of the call,
this can be either a JSON array [...]
or a JSON object {...} */
}
{"ok": false, "error": "UNKNOWN_RESOURCE"}
All requests that require authentication use HTTP Basic Authentication. The username should be the account's AccessKey, and the password should be the account's SecretKey. You obtain your individual AccessKey and SecretKey pair by signing up for an InOut account.
All interactions with the InOut API are secured by communicating over the SSL encrypted HTTPS protocol.
Several InOut API calls support an optional callback parameter which can be used to be notified when asynchronous operations are completed. For the callback mechanism to work correctly you must provide a valid absolute HTTP or HTTPS URL which can be called from the internet.
All usage examples in this document rely on the command line http client curl (http://curl.haxx.se/) but can be performed with any other http client.
What is a profile?
A conversion profile is a predefined template which contains actions to apply during a conversion. Depending on its type, the profile may expose parameters through which the conversion process can be parametrized.
Example:
The profile "IMAGE_TO_JPEG" converts an image of arbitrary file type to the JPEG format. The profile can be parametrized through parameters like "width", "height", "compression" and so on to further specify the desired output.
Retrieves a list of available conversion profile Ids.
https://api.inout.io/conversions/
GET
true
none
Returns a list of profiles. Every profile contains the following attributes:
| Attribute | Description |
|---|---|
| id | Unique Profile Id |
curl -u key:secret https://api.inout.io/profiles/
{"ok": true, "result": [
{"id": "IMAGE_TO_JPEG"},
{"id": "IMAGE_TO_PNG"},
{"id": "IMAGE_TO_GIF"},
// ...
]}
Retrieves details for a specific conversion profile, including the available profile parameters.
https://api.inout.io/conversions/[Id of Profile]
GET
true
none
Returns a detailed profile object, containing the following attributes:
| Attribute | Description |
|---|---|
| id | Unique Profile Id |
| params | Map of available profile parameters and their default values. |
curl -u key:secret https://api.inout.io/profiles/IMAGE_TO_JPEG
{"ok": true, "result": {
"id":"IMAGE_TO_JPEG",
"params":{
"width": null,
"height": null,
"aspect": null,
"quality": null,
"background": null,
"transparentColor": null
}
}}
Creates a new conversion, retrieving an input file from the given URL and converting it with a single profile and parameters to an output file.
https://api.inout.io/conversions/
POST
true
| url | Url of resource to convert. |
| profile | Profile id to apply to the resource. |
| param.[name] | Optional. One or multiple profile parameters prefixed with "param.", e.g. "param.width", "param.height",... For a list of valid params refer to the profile detail. |
| callback | Optional. Url for asynchronous signaling of conversion finish event |
Returns a JSON object containing the id of the created conversion.
| Attribute | Description |
|---|---|
| id | Unique conversion id |
If a callback url is provided, InOut will append the conversion id as "_inout_conversion_id" request parameter at the end of the url and execute the callback with HTTP GET at the time the conversion has finished.
curl -X POST -u key:secret -d "url=http://gallery.photo.net/photo/7678634-lg.jpg&profile=IMAGE_TO_JPEG¶m.width=320¶m.height=240" https://api.inout.io/conversions/
{"ok": true, "result": {
"id": "d1c6f74577059515ff1bb5ce0f7bef66"
}}
Creates multiple conversions in one step, retrieving an input file from the given URL once and converting it with multiple profiles to multiple output files.
The main purpose of this call is that input files are downloaded only once in contrary to submitting several single profile conversions which would always lead to downloading the source again for every single conversion.
https://api.inout.io/conversions/
POST
true
| url | Url of resource to convert. |
| profile[n] | Id of profile to apply to the resource. "[n]" is to be substituted with the a profile index starting at 0. Example: profile0 = IMAGE_TO_JPEG, profile1 = IMAGE_TO_PNG, ... |
| param[n].[name] | Optional. One or multiple profile parameters prefixed with "param[n]." refering to the the n-th conversion profile, e.g. "param0.width=100", "param1.width=200",... For a list of valid params refer to the profile detail. |
| callback | Optional. Url for asynchronous signaling of conversion finish event for each conversion |
Returns a list of JSON objects each containing the id of the created conversion.
| Attribute | Description |
|---|---|
| id | Unique Conversion Id |
curl -X POST -u key:secret -d "url=http://gallery.photo.net/photo/7678634-lg.jpg&profile0=IMAGE_TO_JPEG¶m0.width=320¶m0.height=240&profile1=IMAGE_TO_PNG¶m1.width=100¶m1.height=100" https://api.inout.io/conversions/
{"ok": true, "result":[
{"id": "d1c6f74577059515ff1bb5ce0f7bef66"},
{"id": "2c3bf1ef764bc037c8d9823e82e75c6b"}
]}
Returns a detailed conversion object containing the conversion status for a specified conversion id.
https://api.inout.io/conversions/[ID of Conversion]
GET
true
- none -
Returns a JSON object containing conversion details.
| Attribute | Description |
|---|---|
| id | Conversion Id |
| url | Source Url to be converted |
| profile | Conversion profile Id to be executed |
| params | Conversion profile params as a JSON Map |
| callback | Callback Url |
| create_time | Conversion create time in unix time notation |
| finished | Boolean value. false = the conversion is still running; true = the conversion is finished |
| error | Contains the conversion error code in case the conversion failed |
| in_size | Binary size of Input Url data in bytes |
| in_contenttype | Contenttype of Input data |
| out_url | Url pointing to the conversion output |
| out_size | Binary size of the generated output in bytes |
| out_contenttype | Contenttype of the generated output |
| deleted | Boolean value. false = the conversion can be downloaded from the url given under out_url. true = the conversion output has been deleted and can no longer be downloaded |
curl -u key:secret https://api.inout.io/conversions/d1c6f74577059515ff1bb5ce0f7bef66
{"ok": true, "result":{
"id": "d1c6f74577059515ff1bb5ce0f7bef66",
"url": "http://gallery.photo.net/photo/7678634-lg.jpg",
"profile": "IMAGE_TO_PNG",
"params": {
"width": 320,
"height": 240
},
"callback": "http://www.your.server/inout/callback?obj=123",
"create_time": 1285934400,
"finished": true,
"in_size": 345656,
"in_contenttype": "image/jpg",
"out_url": "http://www.inout.io/output/123342345546546.png",
"out_size": 203434,
"out_contenttype": "image/png"
}}
Returns a list of submitted conversions. The conversions are sorted by create_time in descending order.
https://api.inout.io/conversions/
GET
true
| limit | Optional. Number of maximum results to return. Must be between 1 and 100. Default: 100 |
| offset_create_time | Optional. Returns the result starting at the given create_time offset. |
| offset_id | Optional. Can be used in combination with offset_create_time to further specify the starting point of the result set. The object referenced by offset_id is not included in the result. The first result object is the object following the referenced id. |
Returns a list of JSON objects containing the following attributes:
| Attribute | Description |
|---|---|
| id | Conversion Id |
| create_time | Conversion create time in unix time notation |
| finished | boolean value. false = the conversion is still running; true = the conversion is finished |
| error | Contains the conversion error code in case the conversion failed |
curl -u key:secret https://api.inout.io/conversions/
{"ok": true, "result":[{
"id": "d1c6f74577059515ff1bb5ce0f7bef66",
"create_time": 1285934400,
"finished": true
}, {
"id": "d1c6f74577059515ff1bb5ce0f7bef66",
"create_time": 1285934380,
"finished": true
"error": "DOWNLOAD_ERROR"
}]}
Removes all binary data associated with the conversion and sets the "deleted" attribute of the conversion to true.
https://api.inout.io/conversions/[Id of Conversion]
JSON
DELETE
true
none
curl -X DELETE -u key:secret https://api.inout.io/conversions/d1c6f74577059515ff1bb5ce0f7bef66
{"ok": true}
| Attribute | Description |
|---|---|
| 200 | Indicates that the request was successful. |
| 400 Bad Request | The request body was malformed or the record you are updating has an incorrect field value. A response with this status is often accompanied by a list of errors in the response body. |
| 401 Unauthorized | The credentials specified via HTTP Basic Authentication were invalid. |
| 404 Not Found | The resource you have referenced could not be found. |
| 405 Method Not Allowed | The method you are using to access (GET, POST, PUT, etc.), is not allowed for the requested resource. |
| 500 Internal Server Error | There has been an error from which InOut could not recover. There is a high likelihood that an internal server error represents a bug on the part of InOut. InOut Support automatically receives notifications of these errors for further investigation. |
Get started now and testdrive InOut for free
Please help us to make InOut a better service: