These pages describe the basic public Application Programming Interfaces (API's) that sevenload has to offer.

Beta Stage

Even if this API declares itself to be version 1.0, we treat it as our first beta. We will add many more methods in the following weeks, like uploading, searching, user management and many more. These are non-breaking changes because we will only add more methods. If you dont use them, your code will work even if its strictly designed for the current version of the API.

Future developments

In the future, we will offer many more extended API's. We will support SOAP, Uploading (FTP, HTTP PUT, WebDAV, etc.) and an user authentication system. The user authentication system will allow you to implement a login functionality in your application without getting in touch with the users password.

Get involved!

If you have any comments, wishes or questions about our API do not hesitate to contact us. We've set-up an email adress dedicated to the API, you can mail us at api@sevenload.com.

This section defines all the sevenload specific terms we use in this API documentation. If you have problem with a term not defined here, please contact us to clearify this part of the documentation and for an explanation of the term you do not understand entirely.

Item

We abstract every type of media on the sevenload platform under the term "Item". An item can be a Video, Image or Audio.

This does not mean that every physical file is an item, an item itself consists of many files like the thumbnails, the FLV video file or the freezeframes.

Every item has an unique id, whose schema is described in the "Common Parameter Types" section.

In order to document the XML structure and all allowed values, we do not want to develop our own documentation "standard". Instead, we use XML Schema, a well known standard in the XML world. We can avoid misunderstandings and its machine readable.

Even if you are not familar with XML Schema, you should be able to read it without much problems. Regardless, you may want to learn XML Schema, it's worth it! If you have problems reading the schemas, you may take a look at the W3C's XML schema specification.

We provide a full package of XSD's to validate every API output. If you have specific questions about the result XML you should look in this files. You should have recieved the schemas with this documentation. If not, please contact us and we will sent them to you as soon as possible.

Request and Response Encoding

Every request parameter must be encoded in UTF-8 and every response from the sevenload API will be encoded in UTF-8 as well. If you send non UTF-8 data, the API may behave strange or simply does not work.

Methods and endpoints

Every API method is mapped to an URL which also includes some of the parameters you have to pass to the method. Additionally, some parameters must be passed as HTTP-GET parameters. Each parameter has a type which is documented in this documentation.

Tokens

We use Tokens everywhere in the sevenload API, if you want to call a method you first have to create a token which suits the method (i.e.: a write access token). The token approach has some advantages for you as the user of the API.

1. You don't have to authenticate over and over for each method call. This saves much overhead at your side.
2. You don't have to send your authentication data over insecure networks everytime you call a method.
3. You can obtain a read-only token to implement a read-only mode at your side without doing much checking by yourself. If you call a write method with a read-only token it will fail.

You can obtain a fresh token with the /token/create method. You have to authenticate yourself with your API key and your password to get a token. Tokens have a lifetime and may have a litte counter called 'charges'. Everytime you use a token, one charge will fired and the counter decreases. After the token expires because the lifetime is over or all charges are fired, you have to obtain a new one.

Not every token has charges, this depends on the configuration of your API key. If your API key is configured to use tokens without charges, you will never get in touch which these.

To simplify the handling of the tokens, the used token information is returned after each call in so-called response header. See the responses section for more info about this feature.

Requests

Every API method has an unique URL where your data must be send to. In most cases, the URL itself contains one or more parameters for the method. Additionally, every method may need one or more parameters provided with HTTP GET. Every method has two guranteed GET parameters: The token-id, passed as "token-id" and a username passed as "username".

You should pass the token id and the username everytime you call a method. Even if one of the both parameters is not required, the method will not fail.

Responses

You will always get a XML repsonse which follows a standardized form to ease the parsing. The response starts with the sevenload-api root element which provides some convenience information about the method call. The response attribute will tell you if the call has failed or was executed correctly. With that information, you can directly jump into you errorhandling code without parsing the whole document to investigate if it was executed properly or not. It also provides information about the minor and major version number used for this call.

Next, the so-called header follows. The header starts with a header element containing all header information. At the time of writing and version 1.0, only the token used to call this method is available. The token data in the header, is the current data. One charge has been removed and/or the token has been declared as invalid.

After the header, the payload follows. The payload can either be the the result of the method call or an <errors /> element containing all occoured errors.

Some methods do not need to return any payload. In this special case an empty <void /> element is retuned.

Each Payload is described in the method documentation of every call, so we do an example with some errors in it.

Response Example

<?xml version="1.0" encoding="UTF-8"?>
<sl:sevenload-api major-version="1" minor-version="0" response="failure" 
xmlns:sl="http://api.sevenload.com/rest/1.0">
    <header>
        <used-tokens>
            <token type="read" charges="1" valid="true">
                3858f62230ac3c915f300c664312c63f
            </token>
        </used-tokens>
    </header>
    
    <!-- Here goes the payload, in this example some errors. -->
    <errors>
        <error code="44" for-argument="an-example-argument">
            Call argument is not valid.
        </error>
    </errors>
</sl:sevenload-api>

If an API error occours, the occoured errors are wrapped in an <errors/> element. Every error has an integer code which represents the error in a machine readable way. Aditionally, an error message is provided which explains the error in a human readable way. This message is subject of change and should not be used for errorhandling.

General error codes

Code	Message
10	Guru Meditation, the API is currently not available.
11	The request data is not compatible with this version of the API.
23	The token has expired.
24	The token has no charges left.
25	The token type is not allowed for this request.
26	You have not the permission to request this type of token.
27	The given token does not exist.
42	Unknown call. See documentation.
43	Missing call argument.
44	Call argument is not valid.
45	Access denied, you are not allowed to perform this operation on the subject.
46	You requested an unknown page.
47	The given user does not exist.
48	You are not allowed to perform actions in the name of this user.

Remember, you should not parse the error message for your errorhandling. Use the error code instead.

Every parameter, the ones in the URL itself and the passed GET parameters, are typified. For consistency, we describe the types with XML Schema too.

The parameters itself are not encapsuled in XML, we only use XSD to describe the types. No more, no less.

token-id

The token id is a hexadecimal representation of a MD5 hash. See the Tokens section for further details.

<xsd:simpleType name="token-id">
	<xsd:restriction base="xsd:string">
		<xsd:pattern value="[a-fA-F0-9]{32}" />
	</xsd:restriction>
</xsd:simpleType>

item-id

Used to identify a specific item on the sevenload platform.

<xsd:simpleType name="item-id">
	<xsd:restriction base="xsd:string">
		<xsd:pattern value="[a-zA-Z0-9]{7}" />
	</xsd:restriction>
</xsd:simpleType>

album-id

Used to identify a specific album on the sevenload platform.

<xsd:simpleType name="album-id">
	<xsd:restriction base="xsd:string">
		<xsd:pattern value="[a-zA-Z0-9]{7}" />
	</xsd:restriction>
</xsd:simpleType>

username

Used to identify a specific user on the sevenload platform. Like all parameters, it has to be UTF-8 encoded, and may therefore contain special characters like german umlauts or a french circumflex accent character.

<xsd:simpleType name="username">
	<xsd:restriction base="xsd:string">
		<xsd:minLength value="3" />
		<xsd:maxLength value="25" />
	</xsd:restriction>
</xsd:simpleType>

per-page

Used to specify the amount of results per page. The value is limited due to possible performance problems.

<xsd:simpleType name="per-page">
	<xsd:restriction base="xsd:int">
		<xsd:minInclusive value="1" />
		<xsd:maxInclusive value="50" />
	</xsd:restriction>
</xsd:simpleType>

Token related methods

URL	Description
/token/create	Creates a new token for the given API key.
/token/token-id	Requests information about the token.

Item related methods

URL	Description
/item/item-id	Requests general information about the item.
/item/item-id/delete	Deletes the item from the sevenload platform.
/item/item-id/update	Allows to set some fields like the title of the item.
/item/item-id/tags/add	Adds one or more tags to the item.
/item/item-id/tags/remove	Removes one or more tags from the item.
/item/item-id/tags/set	Fist, all tags are deleted and the given tags will be set to the item.

Album related methods

URL	Description
/album/album-id/items	Requests all item information for every item in the album.
/album/album-id/items/images	Requests all item information for every image item in the album.
/album/album-id/items/video	Requests all item information for every video item in the album.
/album/album-id/items/add	Adds an item to the album.
/album/album-id/items/remove	Removes an item from the album.

Creates a new token for the given API user. You have to specify a token type if you want to create token with write access. Because of the nature of this method, no token is needed to execute this method without any errors.

Method specific types

There is already a 'token-type' XSD type in the response XSD files. Although they are very similar, they are not the same!

token-type

All possible token types

<xsd:simpleType name="token-type">
	<xsd:restriction base="xsd:string">
		<xsd:enumeration value="read" />
		<xsd:enumeration value="write" />
		<xsd:enumeration value="read-write" />
	</xsd:restriction>
</xsd:simpleType>

Parameters

Name	Required	Type	Default	Description
username	Yes	xsd:string	Nothing	The name of the API user for which you want to create a token for.
password	Yes	xsd:string	Nothing	The password for the API user.
type	No	token-type	read	The type for the created token.

Method specific errors

Code	Message
23003	The username or password combination is wrong or the user is not a valid API user.

Response Payload

XSD complexType token

This methods allows you to get informations about a token.

Response Payload

XSD complexType token

This methods allows you to get informations about an item. This includes the title, description, tags, views and so on.

Response payload

XSD complexType item

This methods allows you to delete an item.

Response payload

XSD complexType item

This methods allows you to update an item. You can set the title, description and so on. None of the parameters are required, simply set the fields you want to set and you are done.

Parameters

Name	Required	Type	Description
title	No	xsd:string	The title of the item.
description	No	xsd:string	The description of the item.
language	No	ISO639-1	The language of the item.
allowFeedback	No	xsd:boolean	Do you want to allow feedback for this item?

Response payload

XSD complexType item

With this method you can add one or more tags to an item. A tag consists simply of a name and the language of the tag.

To add multiple tags, simply pass the tags[]['name'] parameter multiple times with different tags. To handle the language of the tags correctly, you have to pass the tags[]['language'] parameter in the same order as the tags. If you add the tag foo and then bar you have to add the languages in the same order: foolanguage and than barlanguage.

All tag related methods are using this rules for tags and their language.

Parameters

Name	Required	Type	Description
tags[]['name']	Yes	xsd:string	The tag you want to add.
tags[]['language']	No	ISO639-1	The language of the added tag.

Response Payload

XSD complexType item

This method removes all tags from the item and then it adds all the given tags.

This method follows the same rules as the /item/item-id/tags/add method.

Parameters

Name	Required	Type	Description
tags[]['name']	Yes	xsd:string	The tag you want to add.
tags[]['language']	No	ISO639-1	The language of the added tag.

Response Payload

XSD complexType item

Removes one or more tags from the item. If the tag to remove have a specific language, you also have to provide the language of the tag.

This method follows the same rules as the /item/item-id/tags/add method.

Parameters

Name	Required	Type	Description
tags[]['name']	Yes	xsd:string	The tag you want to remove.
tags[]['language']	No	ISO639-1	The language of the tag to remove.

Method specific errors

Code	Message
23002	The given tag does not exist.

Response Payload

XSD complexType item

Returns a list of all items in this album, if the result is too big its splitted into multiple pages. You can pass the perPage parameter to specify the amount of items per page. Use the page attribute to select the page to request.

Parameters

Name	Required	Type	Default	Description
page	No	xsd:positiveInteger	0	The page you want to request.
perPage	No	per-page	25	The amount of items per page.

Response Payload

XSD complexType item-list

Returns a list of all video items in this album, if the result is too big its splitted into multiple pages. You can pass the perPage parameter to specify the amount of items per page. Use the page attribute to select the page to request.

This method only returns video items, nothing else.

Parameters

Name	Required	Type	Default	Description
page	No	xsd:positiveInteger	0	The page you want to request.
perPage	No	per-page	25	The amount of items per page.

Response Payload

XSD complexType item-list

Returns a list of all image items in this album, if the result is too big its splitted into multiple pages. You can pass the perPage parameter to specify the amount of items per page. Use the page attribute to select the page to request.

This method only returns image items, nothing else.

Parameters

Name	Required	Type	Default	Description
page	No	xsd:positiveInteger	0	The page you want to request.
perPage	No	per-page	25	The amount of items per page.

Response Payload

XSD complexType item-list

Adds one or more items to an album. You can pass multiple items[] parameters to add multiple items to the album.

Parameters

Name	Required	Type	Description
items[]	Yes	item-id	The item you want to add to the album.

Removes one or more items from an album. You can pass multiple items[] parameters to remove multiple items from the album.

Parameters

Name	Required	Type	Description
items[]	Yes	item-id	The item you want to remove from the album.