pl en

mydrmspace.com - open digital watermarking platform - your creation is where your data is

Welcome | Check file | Login | Register | Search | Top Coders | Terms of Use | Contact us

Mydrmspace.com API documentation – version 0.4 (27.06.2011.)

1. General information

1.1. Requirements

To use API you need to have service login and password (serviceName and serviceKey) – they are identifying API user. Those parameters are also needed for OAuth.

API uses double login mechanism – login and password of user and login and password of service. User's login and password are identifying end user – the owner of signed media.

It is possible (and recommended) to use OAuth authorization.

Endpoint for requesting token is: https://mydrmspace.com/requestToken.php

Endpoint for getting access token is: https://mydrmspace.com/accessToken.php

Those endpoints are also available via plain HTTP (without TLS).

1.2. Working

Mydrmspace.com API works on HTTP protocol (with TLS). Due to HTTP characteristics communication is realized in query (question) – response (answer) order. Every pair query – response is independent from previous ones. API uses unique session identifiers to make logicaly relations for every query from the same user.

Queries and responses are written in XML. API uses UTF-8 character encoding.

1.3. HTTP POST message structure

Queries are sent with HTTP POST method with Content-Type multipart/form-data. Message sent to server is stored in „query” field and is mandatory. Files are sent as „media” field and are used in <sign/> and <read/> queries. With other types of queries field „media” is unused.

Server response is, in most cases, sent with application/xml Content-Type. Downloading file is the only exception, because files are sent with misc/binary Content-Type.

API is available at https://mydrmspace.com/api/. It is possible to use non SSL communication, but we don't recommend this.

2. Message structure

Messages (both from and to server) are build in XML. Root element of every message is <mydrmspace/>. Action is defined with element inside it: <hello/>, <sign/>, <read/>, <check/>, <file/> or <bye/>.

Server response is built similar (with the same second level node name). The only exception is downloading file - <file method=”get”/>, because server doesn't answering with XML but with file contents.

2.1. Query structure

Example query:

<?xml version="1.0"?>
<mydrmspace>
<hello>
<login>abc</login>
<password>def</password>
<servicename>ghi</servicename>
<servicekey>jkl</servicekey>
<client>API Client 1.0</client>
</hello>
</mydrmspace>

2.2. Response structure

Example response:

<?xml version="1.0"?> 
<mydrmspace>
<hello status="ok">
<status>100</status>
<session>aae666d23b28c8adb6ccbe4265993266</session>
</hello>
</mydrmspace>

Response has root node <mydrmspace/> and second level node with the same name as in query. There are always third level nodes <session/> and <status/>. <session/> contains unique session identifier and <status/> contains three digit response code.

2.3. Error response structure

Example error response:

<?xml version="1.0"?> 
<mydrmspace>
<hello status="error">
<status>900</status>
<info>Invalid username or password</info>
</hello>
</mydrmspace>

Errors are built similar. They have response code equal or greater than 900. Element <info/> contains short text message with error description.

2.4. Response codes

Value Description
100 Login correct
201 Task queued
300 Task done
301 Task is still being proceeded
900 Login error (incorrect login or password)
901 Not logged
910 File can't be signed
911 File can't be read
912 Over reading limit
920 No file
921 Can't download given URL
930 No task
940 Can't comment, comments are turned off
950 Can't remove file
999 General error (every other reason)

3. Message description

3.1. <hello/>

<hello/> message is used to login.

Old convention:

Element Parameter Description
login
User login
password
User password
servicename
Service login (API login)
servicekey
Service password (servcekey, API password)
client
(optional) Name of service or software (example: „TurboMDS 3.1”)
session
(optional) Session identifier. This is the only message, where session is not obligatory

 

New convention (OAuth):

Element Parameter Description
token
Access token
token_secret
Access token secret
client
(optional) Name of service or software (example: „TurboMDS 3.1”)
session
(optional) Session identifier. This is the only message, where session is not obligatory

 

Example query (old convention):

<?xml version="1.0"?>
<mydrmspace>
<hello>
<login>abc</login>
<password>def</password>
<servicename>ghi</servicename>
<servicekey>jkl</servicekey>
<client>API Client 1.0</client>
</hello>
</mydrmspace>

Example query (new convention - OAuth):

<?xml version="1.0"?>
<mydrmspace>
<hello>
<token>ghi</token>
<token_secret>jkl</token_secret>
<client>API Client 1.0</client>
</hello>
</mydrmspace>

Correct login will result status 100 and will generate new session ID (if wasn't given). Example response:

<?xml version="1.0"?> 
<mydrmspace>
<hello status="ok">
<status>100</status>
<session>aae666d23b28c8adb6ccbe4265993266</session>
</hello>
</mydrmspace>

3.2. <sign/>

<sign/> message is for signing files. Must be sent with file or URL (see 1.3.)

Message structure:

etc.

Element Subelement Parameter Description
session     Session identifier
coder     Coder ID as an integer value.
additionalWatermark     (optional) If specified, signed file will have additional visible/audible watermark.
url     (optional) If specified and if "media" HTTP request field isn't existing, server will try to download the file from given URL and then will try to sign.
metadata

(optional) Metadata. If not given no metadata will be stored (it will be possible to fill it using WWW interface). The server will sign file and assign ID and timestamp.
hlt   (optional) Mydrmspace Hidden Link Technology™ field. Always public
creator
(optional) Field „creator"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
title
(optional) Field „title"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
contributor
(optional) Field „contributor"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
description
(optional) Field „description"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
genre
(optional) Field „genre"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
coverage
(optional) Field „coverage"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
date
(optional) Field „date"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
format
(optional) Field „format"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
identifier
(optional) Field „identifier"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
language
(optional) Field „language"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
publisher
(optional) Field „publisher"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
relation
(optional) Field „relation"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
rights
(optional) Field „rights"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
source
(optional) Field „source"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
subject
(optional) Field „subject"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
type
(optional) Field „type"
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
userdef1
(optional) User defined field 1
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
name (optional) User defined field name
userdef2
(optional) User defined field 2
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
name (optional) User defined field name
userdef3
(optional) User defined field 3
public (optional) If specified, and is set to "yes" field will be public. Otherwise, the field will be private (default).
name (optional) User defined field name
comments   (optional) Possible values: 0 or 1. If exists and contains zero comments will be disabled. Otherwise comments will be enabled.

Correct response has 201 response code and <task/> field containing ID of queued task. Example response:

<?xml version="1.0"?> 
<mydrmspace>
<sign status="queued">
<status>201</status>
<session>ced985e7a7f508ad150cba2f9c897565</session>
<task>1193</task>
</sign>
</mydrmspace>

Task ID (<task/>) can be used in <check/> query to check task status.

3.3. <read/>

<read/> message is used to reading metadata from file. With this message file to be read (or URL) must be sent (see 1.3.)

Element Parameter Description
session
Session identifier
coder
Coder ID as an integer value
url
(optional) URL of the file to download. time. File will be downloaded only if "media" HTTP field won't exist.

Correct response has 201 response code. <read/> response is built like <sign/> response – exists <task/> element:

<?xml version="1.0"?> 
<mydrmspace>
<read status="queued">
<status>201</status>
<session>ced985e7a7f508ad150cba2f9c897565</session>
<task>1194</task>
</read>

3.4. <check/>

<check/> message is used to checking task status.

Element Parameter Description
session
Session identifier
task
Task ID (from <read/> or <sign/> response)

There are two answers: „still proceeding” (response code 301) and „task done” (response code 300).

„Still proceding” - 301 response example:

<?xml version="1.0"?> 
<mydrmspace>
<check status="wait">
<status>301</status>
<session>ced985e7a7f508ad150cba2f9c897565</session>
<info>Wait, this task is still proceeding</info>
</check>
</mydrmspace>

„Task done” response (300) is more complicated and contains information about metadata read from file or saved to file. In both cases response has the same structure and contains public (and only public) metadata of file.

If file is not signed (reading file without digital watermark) <metadata/> element will be empty.

If file is signed (reading file with digital watermark or succesful file signing) <metadata/> will have <id/> and <timestamp/> subelements at least.

<metadata/> structure is identical to structure used in <sign/> query (see 3.2.).

<check/> response structure with 300 response code:

Element Subelement Parameter Description
session

Session identifier
metadata

Metadata of file
id
ID of this file. If this field doesn't exist it means that file is not signed.
timestamp
Timestamp of this file. If this field doesn't exists it means that file is not signed.
mydrmspaceinfo
Information from Mydrmspace.com
Other subelements like <metadata/> in <sign/> (see 3.2.)

Example response of checking task of signing file or reading signed file:

<?xml version="1.0"?> 
<mydrmspace>
<check status="ok">
<status>300</status>
<session>ced985e7a7f508ad150cba2f9c897565</session>
<metadata>
<id>87125616</id>
<timestamp>2009-08-19 11:19:35.975742</timestamp>
<creator>Author</creator>
<title>My title</title>
<userdef1 name="My field 1">My field value</userdef1>
<mydrmspaceinfo>Powered by Mydrmspace.com</mydrmspaceinfo>
</metadata>
</check>
</mydrmspace>

Example response of checking task of reading non signed file:

<?xml version="1.0"?> 
<mydrmspace>
<check status="ok">
<status>300</status>
<session>ced985e7a7f508ad150cba2f9c897565</session>
<metadata/>
</check>
</mydrmspace>

Sometimes signing or reading file can't be done (wrong file format, file is corrupted etc.). In these cases <check/> response will have error response code 910 (can't be signed) or 911 (can't be read).

3.5. <file/>

<file/> message is used to downloading or deleting files from the server. Action is defined by method parameter and file is selected by id parameter (example: <file method="get id="8721300">).

Parameter Description
method Action to do. One of following values must be chosen:
  • delete – deleting the file from server
  • get – downloading the file
  • list - listing downloadable files
id File identifier (taken from <id/> field in <metadata/>; not needed if method="list")

Of course, in <file/> must be present <session/> element:

Element Parameter Description
session
Session identifier

Example query of deleting file:

<mydrmspace>
<file id="508705264" method="delete">
<session>af726d5b9743d4bcf39a641c926e3502</session>
</file>
</mydrmspace>

Correct response has 300 response code. Example:

<?xml version="1.0"?> 
<mydrmspace>
<file status="ok">
<status>300</status>
<session>af726d5b9743d4bcf39a641c926e3502</session>
</file>
</mydrmspace>

Example query of listing downloadable files:

<mydrmspace>
<file method="list">
<session>af726d5b9743d4bcf39a641c926e3502</session>
</file>
</mydrmspace>

Correct response has 300 response code. ID of file is contained by <track/> element. In <list/> element can be zero (if no files), one or more <track/> elements. Example:

<?xml version="1.0"?> 
<mydrmspace>
<file status="ok">
<status>300</status>
<session>af726d5b9743d4bcf39a641c926e3502</session>
<list>
<track>398156003</track>
</list>
</file>
</mydrmspace>

Important!

<file/> query with method=”get” doesn't generate XML response! Response for this type of query are file contens. If there is no file, response will be zero bytes long!

3.6. <coders/>

<coders/> is used to list information about coders and available signatures. Usage is very simple.

ElementParameterDescription
session   Session identifier

Example query:

<?xml version="1.0"?> 
<mydrmspace>
<coders>
<session>af726d5b9743d4bcf39a641c926e3502</session>
</coders>
</mydrmspace>

Example response:

<?xml version="1.0"?> 
<mydrmspace>
<coders>
<session>af726d5b9743d4bcf39a641c926e3502</session>
<status>300</status>
<coder type="audio" number="1" available="10"/>
<coder type="image" number="7" available="446"/>
<coder type="image" number="9" available="99"/>
</coders>
</mydrmspace>

Every available coder is represented by on <coder/> element. Those element have three attributes: "type" - type of coder, "number" - it's ID and "available" - number of signatures to use.

3.7. <comments/>

<comments/> message is used for counting, adding and getting comments.

Parameter Description
method Action to do. One of following values must be chosen:
  • count - counting comments (returns number of comments)
  • add - adding comments
  • get - getting comments
id File identifier (taken from <id/> field in <metadata/>)
from Indicates number (position) of first comment to return; required by method="get"
limit Indicates maximum number of comments to return. Maximum allowed value is 100; required by method="get"
externalUser Name of user in external service; Optional, used by method="add"

Some information must be present as subelements.

Element Subelement Parameter Description
session     Session identifier
comment     Comment text

Example query of counting comments:

<?xml version="1.0"?> 
<mydrmspace>
<comments method="count" id="123456">
<session>af726d5b9743d4bcf39a641c926e3502</session>
</comments>
</mydrmspace>

Example response:

<?xml version="1.0"?>
<mydrmspace>
<comments status="ok">
<status>300</status>
<session>af726d5b9743d4bcf39a641c926e3502</session>
<count>379</count>
</comments>
</mydrmspace>

If comments for selected ID are on, response has code 300 and element <count/> which contains number of comments. Otherwise response has error code 940.

Example query of getting comments:

<?xml version="1.0"?>
<mydrmspace>
<comments method="get" id="131202249" from="0" limit="100">
<session>46846296be723a8e6f91255bf4e3a990</session>
</comments>
</mydrmspace>

Example response:

<?xml version="1.0"?>
<mydrmspace>
<comments status="ok">
<status>300</status>
<session>46846296be723a8e6f91255bf4e3a990</session>
<list>
	<comment id="486" time="2009-10-25 12:37:29" user="testuser" service="test" externalUser="Joe">Cool!</comment>
	<comment id="485" time="2009-10-25 12:37:29" user="testuser" service="test" externalUser="Melanie">Awesome!</comment>
	<comment id="484" time="2009-10-25 12:37:28" user="testuser">Very, very, very good!</comment>
</list>
</comments>
</mydrmspace>

As in method="count", if selected ID has turned on comments, response code will be 300. Otherwise it will be 940.

Comments are returned as above. All comments are inside <list/> element. Every comment has it's own ID, time, name of user (user login in Mydrmspace.com). If comment was published by API, there are two additional parameters: service - external service name and externalUser - login in external service. It is possible that externalUser is empty.

Example query of adding comment:

<?xml version="1.0"?>
<mydrmspace>
<comments method="add" id="131202249" externalUser="Bożydar">
<session>efc0ac1d25c36de3f4b41218cc3a2464</session>
<comment>Nice thing!</comment>
</comments>
</mydrmspace>

Parameter externalUser is optional, comment text is inside <comment/> element.

Example response:

<?xml version="1.0"?>
<mydrmspace>
<comments status="ok">
<status>300</status>
<session>efc0ac1d25c36de3f4b41218cc3a2464</session>
</comments>
</mydrmspace>

When everything is ok, response has status 300. Otherwise it is 940.

3.8. <bye/>

<bye/> is simple logout message:

Element Parameter Description
session   Session identifier

Example query:

<?xml version="1.0"?> 
<mydrmspace>
<bye>
<session>af726d5b9743d4bcf39a641c926e3502</session>
</bye>
</mydrmspace>

Example response:

<?xml version="1.0"?> 
<mydrmspace><bye/></mydrmspace>

Changelog

Version 0.2

Version 0.3

Version 0.4:

Welcome | Check file | Login | Register | Search | Top Coders | Terms of Use | Contact us

Upload coder & decoder | HLT | API documentation | API PHP class | Developers registration | Ideas