JOOMEO SERVICES
JOOMEO A.P.I. VERSION 0.4 BETA
w w w . a i r s e n s . c o m w w w . j o o m e o . c o m contact@joomeo.com
SOMMAIRE
JOOMEO SERVICES
.........................................................................................................................................3 GETTING STARTED
...........................................................................................................................................3 API KEY
3 CURRENT RELEASE
3 API OVERVIEW
.................................................................................................................................................4 CONVENTIONS
4 API METHODS
..................................................................................................................................................6 VERSION
6 SESSIONS
8 USER
11 USER.COLLECTIONS
23 USER.FILE
29 API ERRORS CODES
.........................................................................................................................................33 ANNEXES
.........................................................................................................................................................34
2
- © 2008 AIRSENS -
JOOMEO SERVICES
Joomeo’s Application Programming Interface (API) allows you to build your own creative applications around the content created on Joomeo. You can retrieve, explore collections / albums , pictures from a Joomeo space. You'll need an API Key to get started, and need to use XML-RPC (1) to interact with the service.
GETTING STARTED
Anyone is free to write application to do cool stuff with available Joomeo data via our API. Follow the steps below to build your first application :
‣ Read the Joomeo API documentation ‣ Sign up for a user account ‣ Register for an API Key (Public or Commercial)
API KEY
To use Joomeo's API, you need an API key. Each individual application or use of the API can use its own key. It also helps us track how it's being used so we can improve it. We encourage you to develop Commercial applications to build your business on top of Joomeo. There are few exceptions on commercial applications and we invite you to contact us for clarification. Also note that the Joomeo name, the Joomeo logo are owned and trademarked by Airsens and may not be used without permission. Have questions? Please contact us with anything you might want to know : api_developer@joomeo.com.
CURRENT RELEASE
Joomeo API version: 0.4 Beta
3
- © 2008 AIRSENS -
API OVERVIEW
The Joomeo API consists of a set of callable methods that allow you to make remote procedure calls to the Joomeo XML-RPC Server endpoint over the internet. Every HTTP Request must use the method POST. Joomeo XMLRPC API endpoint is available at the URL: http://api.joomeo.com/xmlrpc.php
CONVENTIONS
AUTHENTICATION
Every Joomeo API call must include the API Key. There is no anonymous access type.
LIMITS
The maximum life time of a session is limited to 60 minuts.
XML-RPC REQUEST FORMAT
method_name param1_name value param2_name < type_param >value ..... ..... paramn_name < type_param >value
4
- © 2008 AIRSENS -
XML-RPC RESPONSE FORMAT
[array I struct... ] value
ERROR MESSAGES
Error messages are returned as XML messages with an error code and an error message. The error message is for debugging only. It can change without notice and it is also not suitable for displaying to the user.
faultCode value faultString string
5
- © 2008 AIRSENS -
API METHODS
VERSION
ABOUT
Returns the current API version and the list of available methods. Method Name : joomeo.version.about Request format
joomeo.version.about Response format
apiDocsUrl http://api.joomeo.com/JoomeoAPI.pdf apiName JOOMEO XML-RPC API apiVersion 0.2 apiStatus Beta
6
- © 2008 AIRSENS -
• Method Name : system.listMethods
Request format
system.listMethods Response format
joomeo.session.init joomeo.session.initContact joomeo.user.getCollectionList joomeo.user.getFilesList joomeo.user.collection.getFilesList joomeo.user.collection.getNumberOfFiles joomeo.user.getHubList joomeo.user.file.getBinary joomeo.version.about system.listMethods system.methodHelp system.methodSignature system.multicall system.getCapabilities
7
- © 2008 AIRSENS -
SESSIONS
INIT
Method used to initialize a user session and method of the API call in the application. Method Name : joomeo.session.init Arguments Name apikey (Required) spacename (Required) login (Required) password (Required)
sets up internal control structures. Init must be the first
Type string string string string
Description Your application API key. Joomeo space name Your login associated to the Joomeo space name. Your password.
Returns : The session id and the type of the session Structure : Member name Type Description sessionid string Unique identifiant of the session sessionType int 0 - User Session, 1 - Contact Session
Request format
joomeo.session.init apikey 12345a12345b12345c12345d spacename MyFamily login John password MyPassword
8
- © 2008 AIRSENS -
Response format
sessionid adb7bf8f65f858b13bfb0c271de01206 < name>sessionType 0
INITCONTACT
Method used to initialize a contact session and sets up internal control structures. InitContact must be used to explore hubs. Method Name : joomeo.session.initContact Arguments Name apikey (Required) sessionid (Required) contactid (Required)
Type string string string
Description Your application API key. Session Id Contactid returned from the getHubList Method.
Returns : The sesssion id and the type of the session Structure : Member name Type Description sessionid string Unique identifiant of the session sessionType int 1 - Contact Session Request format
joomeo.session.initContact apikey 12345a12345b12345c12345d sessionid 50d289fd9bca5ce9841f4c3b586c0646
9
- © 2008 AIRSENS -
contactid NTc4YjIyZDDzriVfcogW7A%3D%3D%0D%0A Response format
sessionid 3c2cb6d2fc47f6769e107538f6f6656d sessionType 1
10
- © 2008 AIRSENS -
USER
GETCOLLECTIONLIST
Method used to get the list of collections or albums of the specified sessionid. Method Name : joomeo.user.getCollectionList Arguments Name apikey (Required) sessionid (Required) type orderby
Type string string int string
Description Your application API key. Session Id 0 for Collections - 2 for Albums (0 by default) “date” or “name” - (date by default)
Returns : The list of collections or albums, on
. Array of Structure : Member name Type collectionid string label string orderby string date string createddate string public string allowdownload string allowupload string folderid string
depending on the specified type, of the specified sessionid sort
Description Identifiant of the collection label of the collection sort by criteria date of creation by the user date of creation in the database 0 (private) - 1 (public) 0 (No) - 1 (Yes) 0 (No) - 1 (Yes) Identifiant of the folder
Request format joomeo.user.getCollectionList apikey 12345a12345b12345c12345d sessionid 50d289fd9bca5ce9841f4c3b586c0646 type 0 orderby date
11
- © 2008 AIRSENS -
Response format collectionid NTc4YjIyZDCXMkyzQfxmWA%3D%3D%0D%0A label Collection 1 orderby date date 1223021909 createddate 1223021718 public 0 allowdownload 1 allowupload 0 folderid collectionid NTc4YjIyZDAmo07w43O0dw%3D%3D%0D%0A label Collection 2 orderby date
12
- © 2008 AIRSENS -
date 1218201996 createddate 1218201828 public 0 allowdownload 1 allowupload 0 folderid NTc4YjIyZDBCu0sCh9%2FR2w%3D%3D%0D%0A
GETFILESLIST
Method used to get the list of photos/videos of a given sessionid. Method Name : joomeo.user.getFilesList Arguments Name apikey (Required) sessionid (Required) orderby
random startresult maxresult
Type string string string
int int int
Description Your application API key. Session Id “date” or “name” - (date by default) Generate a Random result sort order : 0 (No) - 1 (Yes) - (0 by default) Start index to get files list (used if maxresult >0) (0 byDefault) Number of photos to return : 0 or N - (0 - unlimited by default)
Returns : A list of photos properties. Array of Structure : Member name Type fileid string filename string rotation string rating string type_mime string size string
13
Description Identifiant of the file Name of the file rotation in degree rate of the picture Mime type of the file size in bytes
- © 2008 AIRSENS -
width height date_shooting date_creation allowdownload collectionid
string string double double string string
width of the picture height of the picture shooting date of the picture creation date of the picture 0 (No) - 1 (Yes) Parent Collection Id
Request format joomeo.user.getFilesList apikey 12345a12345b12345c12345d sessionid 50d289fd9bca5ce9841f4c3b586c0646 orderby date random 0 startresult 20 maxresult 20 Response format fileid NTc4YjIyZDCE2zKHkYzRiw%3D%3D%0D%0A filename
14
- © 2008 AIRSENS -
15
AnnaMarie.jpg rotation 0 rating 0 type_mime image/jpeg size 597810 width 1440 height 900 date_shooting 1.085775444E+12 date_creation 1.218201944E+12 allowdownload 1 collectionid MmUzN2M3ZWTRvA5sYBbJOw%3D%3D%0D%0A fileid NTc4YjIyZDB0TDCs31thug%3D%3D%0D%0A filename BlackDog.jpg rotation 0 rating 0 type_mime image/jpeg
- © 2008 AIRSENS -
16
size 228704 width 2560 height 1600 date_shooting 1.214466532E+12 date_creation 1.223021747E+12 allowdownload 1 collectionid MmUzN2M3ZWTRvA5sYBbJOw%3D%3D%0D%0A fileid NTc4YjIyZDAXNvzDYEaopQ%3D%3D%0D%0A filename BlueridgeMountains.jpg rotation 0 rating 0 type_mime image/jpeg size 1331154 width 2560 height 1600 date_shooting 1.214466532E+12
- © 2008 AIRSENS -
date_creation 1.218201862E+12 allowdownload 1 collectionid MmUzN2M3ZWTRvA5sYBbJOw%3D%3D%0D%0A
GETNUMBEROFFILES
Method to get the number of the photos of a given sessionid. Method Name : joomeo.user.getNumberOfFiles Arguments Name apikey (Required) sessionid (Required)
Type string string
Description Your application API key. Session Id
Returns : The number of photos of the given sessionid.. Structure : Member Name Type Description nbfiles int Number of files in the collection or album Request format joomeo.user.getNumberOfFiles apikey 12345a12345b12345c12345d sessionid 0f16a26a812a1621b673211123501af9
17
- © 2008 AIRSENS -
Response format nbfiles 147
GETHUBLIST
Method used to get the list of the hubs. Method Name : joomeo.user.getHubList Arguments Name apikey (Required) sessionid (Required)
Type string string
Description Your application API key. Session Id
Returns : The list of the hubs for a given sessionid. Array of Structure : Member name Type Description contactid string Identifiant of the contact username string Name of the Joomeo space email string Email firstname string FirstName lastname string LastName Request format joomeo.user.getHubList apikey 12345a12345b12345c12345d sessionid 50d289fd9bca5ce9841f4c3b586c0646
18
- © 2008 AIRSENS -
Response format contactid MmUzN2M3ZWRQqBxaKXd6mw%3D%3D%0D%0A username myspace email john.doe@company.com firstname John lastname DOE contactid MmUzN2M3ZWQk8k69Izpcbw%3D%3D%0D%0A username perauscher email peter.rausher@gmail.com firstname Peter lastname Rausher contactid MmUzN2M3ZWRAHGjI6Sh7TA%3D%3D%0D%0A username Steeve
19
- © 2008 AIRSENS -
email steeve.compo@joomeo.com firstname Steeve lastname Compo
ADDCOLLECTION
Method used to add a new collection in the Joomeo Space. Method Name : joomeo.user.addCollection Arguments Name apikey (Required) sessionid (Required) label (Required) previewSize collectionDate
Type string string string int int
Description Your application API key. Session Id Name of the collection Maximum size of the slideshow and the previews (1600 by default) Date of the collection (date of the day by default)
Returns : The collection id of the new collection Structure : Member Name Type Description collectionid string Identifiant of the collection Request format joomeo.user.addCollection apikey 12345a12345b12345c12345d sessionid 0f16a26a812a1621b673211123501af9
20
- © 2008 AIRSENS -
label OTQxMDRiMDZAzRHl8NYTkw%3D%3D%0D%0A previewSize 1600 collectionDate 1227616985 Response format collectionid MmUzN2M3ZWTOwiAp9ts3%2BA%3D%3D%0D%0A
UPLOADBINARY
Method used to upload the binary file to save in a collection with the method saveUploadedFile. Method Name : joomeo.user.uploadBinary Arguments Name apikey (Required) sessionid (Required) data (Required) filename (Required) size (Required)
Type string string base64 string int
Description Your application API key. Session Id The binary data in base64 corresponding to the binary serialized file The name of the binary file with the extension The size of the binary data (in byte)
Returns : An uploadid used in the method saveUploadedFile Structure : Member Name Type Description uploadid string Temporary identifiant of the uploaded file Request format
21
- © 2008 AIRSENS -
joomeo.user.uploadBinary apikey 12345a12345b12345c12345d sessionid 0f16a26a812a1621b673211123501af9 data binary data filename filename.jpg size 1277900 Response format uploadid 1227616985_419
22
- © 2008 AIRSENS -
USER.COLLECTIONS
GETFILESLIST
Method to get the list of the photos contained in given collection or album. Method Name : joomeo.user.collection.getFilesList Arguments Name apikey (Required) sessionid (Required) collectionid (Required) orderby
random startresult maxresult
Type string string string string
int int int
Description Your application API key. Session Id Collection Id “date” ,“name” or “manual” - (date by default) Generate a Random result sort order : 0 (No) - 1 (Yes) - (0 by default) Start index to get files list (used if maxresult >0) (0 byDefault) Number of photos to return : 0 or N - (0 - Unlimited by default )
Returns : The list of photos of the corresponding collection or album. Array of Structure : Member name Type Description fileid string Identifiant of the file filename string Name of the file rotation string rotation in degree rating string rate of the picture type_mime string Mime type of the file size string size in bytes width string width of the picture height string height of the picture date_shooting double shooting date of the picture date_creation double creation date of the picture allowdownload int 0 (No) - 1 (Yes) collectionid string Parent Collection Id
Request format joomeo.user.collection.getFilesList apikey 12345a12345b12345c12345d sessionid 07fcec8470e06fba7e7326d74e9b8865 collectionid MmUzN2M3ZWS1Q63BmNKHuA%3D%3D%0D%0A
23
- © 2008 AIRSENS -
orderby date random 1 maxresult 3
Response format fileid MmUzN2M3ZWTRvA5sYBbJOw%3D%3D%0D%0A filename AnnaMarie.jpg rotation 0 rating 0 type_mime image/jpeg size 597810 width 1440 height 900 date_shooting
24
- © 2008 AIRSENS -
25
1.085775444E+12 date_creation 1.218201944E+12 allowdownload 1 collectionid MmUzN2M3ZWTRvA5sYBbJOw%3D%3D%0D%0A fileid MmUzN2M3ZWTOwiAp9ts3%2BA%3D%3D%0D%0A filename BlueridgeMountains.jpg rotation 0 rating 0 type_mime image/jpeg size 1331154 width 2560 height 1600 date_shooting 1.214466532E+12 date_creation 1.218201862E+12 allowdownload 1 collectionid MmUzN2M3ZWTRvA5sYBbJOw%3D%3D%0D%0A
- © 2008 AIRSENS -
GETNUMBEROFFILES
Method to get the number of the photos contained in given collection or album. Method Name : joomeo.user.collection.getNumberOfFiles Arguments Name apikey (Required) sessionid (Required) collectionid (Required)
Type string string string
Description Your application API key. Session Id Collection Id
Returns : The number of photos of the corresponding collection or album. Structure : Member Name Type Description nbfiles int Number of files in the collection or album Request format joomeo.user.collection.getNumberOfFiles apikey 12345a12345b12345c12345d sessionid 0f16a26a812a1621b673211123501af9 collectionid OTQxMDRiMDZAzRHl8NYTkw%3D%3D%0D%0A Response format
26
- © 2008 AIRSENS -
nbfiles 147
SAVEUPLOADEDFILE
Method to save an uploaded file in a collection. Method Name : joomeo.user.collection.saveUploadedFile Arguments Name apikey (Required) sessionid (Required) collectionid (Required) uploadid (Required) upload.php fileName (Required)
Type string string string string string
Description Your application API key. Session Id Collection Id Upload Id return by the method uploadBinary or by the PHP script name of the uploaded file (with extension)
Returns : The file id of the added file. Structure : Member Name Type fileid string
Description Identifiant of the file
Request format joomeo.user.collection.saveUploadedFile apikey 12345a12345b12345c12345d sessionid 0f16a26a812a1621b673211123501af9 collectionid OTQxMDRiMDZAzRHl8NYTkw%3D%3D%0D%0A uploadid 1227616985_419 filename filename.jpg
27
- © 2008 AIRSENS -
Response format fileid MmUzN2M3ZWTOwiAp9ts3%2BA%3D%3D%0D%0A
28
- © 2008 AIRSENS -
USER.FILE
GETBINARY
Method to download the binary file of a photo contained in given collection or album. If parameter collectionid is Null the method will take into account the current collection id of the photo. Method Name : joomeo.user.file.getBinary Arguments Name Type Description apikey (Required) string Your application API key. sessionid (Required) string Session Id fileid (Required) string File Id of the photo collectionid string Collection Id type (Required) string Format type :
“large” (by default) - size from 640x640 to 1600x1600,
“original” - size original,
“small” - size 240x240,
“medium” - size 500x500,
“degraded” - size 50x50 Returns : The binary data in base64 corresponding to the binary serialized photo. Structure : Member Name Type Description data base64 Binary data mime_type string Mime type of the file size int size in bytes of the file Request format joomeo.user.file.getBinary apikey 12345a12345b12345c12345d sessionid 2aa89193aca45ace5995d905a4e45707 fileid YmRiNWE4NzfjHivguObbFw%3D%3D%0D%0A collectionid YmRiNWE4NzeG5zZzirOmLQ%3D%3D%0D%0A type large
29
- © 2008 AIRSENS -
Response format data binary data mime_type image/jpeg size 304432
30
- © 2008 AIRSENS -
FILE.PHP
Script PHP used to download a photo directly from its URL. Arguments Name apikey (Required) sessionid (Required) fileid (Required) collectionid type (Required)
default (large)
Returns : The data file. URL access http://api.joomeo.com/file.php Request format http://api.joomeo.com/file.php? apikey=12345a12345b12345c12345d&sessionid=2aa89193aca45ace5995d905a4e45707&fileid=YmRiNWE 4NzfjHivguObbFw%3D%3D%0D%0A&collectionid=YmRiNWE4NzeG5zZzirOmLQ%3D%3D%0D %0A&type=large
Type string string string string string
Description Method Your application API key. GET Session Id GET File Id of the photo GET Collection Id GET Format type : “original”, “large”, “small”, “medium”, “degraded” by
GET
UPLOAD.PHP
Script PHP used to upload a file. Arguments Name apikey (Required) sessionid (Required)
Type string string
Description Your application API key. Session Id
Method GET GET
Posted data upload.php must receive a request POST with the following parameters : - an element Content-Type with multipart/form-data - an element Content-Disposition with the attribut name defined on "Filedata" and an attribut name defined on the original file name - the binary data of the file to upload Returns : An upload id used in the method saveUploadedFile URL access http://api.joomeo.com/upload.php Request format http://api.joomeo.com/upload.php? apikey=12345a12345b12345c12345d&sessionid=2aa89193aca45ace5995d905a4e45707 Posted data example
31
- © 2008 AIRSENS -
Content-Type: multipart/form-data; boundary=AaB03x --AaB03x Content-Disposition: form-data; name="Filedata"; filename ="example.jpg" Content-Type: application/octet stream ... contents of example.jpg ... --AaB03x-Response format Success : 1227616985_419 Error : 200
32
- © 2008 AIRSENS -
API ERRORS CODES
100: INVALID XML RPC OBJECT
The passed signature was invalid.
101: INVALID XML RPC METHOD SIGNATURE
The passed signature was invalid.
102: UNKNOWN XML RPC METHOD
Given method doesn’t exist.
200: INVALID API KEY
The API key passed is not valid.
201: API KEY DO NOT EXIST
The API key passed doesn’t exist.
202 : SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or an error occured while initializing the user session.
203 : SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or an error occured while initializing the contact session.
204 : SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or can’t create a session for the contact.
205 : SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or can’t get the session properties.
206 : SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or is not allowed to make this action.
300: LOGIN / AUTHENTIFICATION FAILED.
Invalid connection parameters
301: MISSING / EMPTY REQUIRED PARAMETER.
Missing required parameter param
400: SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or can’t Initialize the user collection
401: SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or can’t get the user collections list
402: SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or can’t Initialize the files list for the collection
403: SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or can’t get the user hubs list
404: SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or an error occured while trying to get the files list
33
- © 2008 AIRSENS -
405: SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or an error occured while trying to get the binary data file
406: SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or an error occured while trying to add a new collection
407: SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or an error occured while trying to add a file into a collection
407001: INVALID PARAMETER UPLOADID
The uploadid is not valid
407002: FILE FORMAT ERROR
The uploaded file format is not supported
407003: INVALID PARAMETER COLLECTIONID
The collectionid is not valid
407004: MONTHLY UPLOAD LIMIT IS REACHED
The Joomeo space has reached its monthly upload limit
408: SERVICE CURRENTLY UNAVAILABLE
The API service is currently unvailable or an error occured while trying to upload binary data
408001: SAVE UPLOADED FILE ERROR
An error occured while trying to save uploaded file in temporary directory
408002: MONTHLY UPLOAD LIMIT IS REACHED
The Joomeo space has reached its monthly upload limit
408003: FILE FORMAT ERROR
The uploaded file format is not supported
ANNEXES
(1) XML-RPC
XML-RPC is a format devised by Userland Software for achieving remote procedure call via XML using HTTP as the transport. XML-RPC has its own web site, www.xmlrpc.com.
34
- © 2008 AIRSENS -
w w w . a i r s e n s . c o m w w w . j o o m e o . c o m contact@joomeo.com