XiboAPI

Create an API for Xibo which supports all the transactions available in Xibo.

Authorization
OAuth will be used to provide authorization for access to the Xibo API.

OAuth Information
Service location: services.php

OAuth methods:
 * XRDS: services.php?xrds
 * Request Token: services.php?service=oauth&method=request_token
 * Authorize Token: index.php?p=oauth&q=authorize
 * Access Token: services.php?service=oauth&method=access_token

XRDS
   xri://$xrds*simple  http://oauth.net/discovery/1.0 #main   http://oauth.net/core/1.0/endpoint/request http://oauth.net/core/1.0/parameters/auth-header http://oauth.net/core/1.0/parameters/uri-query</Type> http://oauth.net/core/1.0/signature/HMAC-SHA1</Type> http://oauth.net/core/1.0/signature/PLAINTEXT</Type> http:///services.php?service=oauth&method=request_token</URI> </Service>  http://oauth.net/core/1.0/endpoint/authorize</Type> http://oauth.net/core/1.0/parameters/uri-query</Type> http:///index.php?p=oauth&q=authorize</URI> </Service>  http://oauth.net/core/1.0/endpoint/access</Type> http://oauth.net/core/1.0/parameters/auth-header</Type> http://oauth.net/core/1.0/parameters/uri-query</Type> http://oauth.net/core/1.0/signature/HMAC-SHA1</Type> http://oauth.net/core/1.0/signature/PLAINTEXT</Type> http:///services.php?service=oauth&method=access_token</URI> </Service> </XRD> </XRDS>

Registered Applications
You must obtain a consumer_key and consumer_secret for your application. Keys for "Supported" applications will be shipped with Xibo meaning no extra steps are required. If you have made your own application you will need to register it with your Xibo Server using the following address:

Register Service: index.php?p=oauth

You will be asked for:
 * Your Name
 * Your email address
 * A URL for your Application
 * A Callback URL

Xibo will (at a later date) have a UI for displaying all registered applications.

Callback URL
The Callback URL will be automatically called by Xibo on a completely Authorize request. It will be called regardless of whether the authorization was successful and will contain an OAuth message indicating the authorize success.

If you do not specify a Callback URL Xibo will show a message requesting the user return to the application once authorized.

Request Formats
Xibo supports the following request formats


 * REST

REST
A simple POST or GET.

To request the Xibo Version method:

services.php?service=rest&method=version

By default the response type is xml. To get a different response type send "&response="

Response Types
Xibo supports the following response types


 * JSON (not implemented)
 * XML

JSON
To return a JSON object specify the response to be JSON (response="json")

A method call returns:

xiboApi({  "stat":"ok",   "response": {...} })

A failure call returns:

xiboApi({  "stat":"error",   "error": {      "code": "[error-code]",      "message": "[error-message]"   } })

XML
A successful call returns this:

<?xml version="1.0" encoding="utf-8" ?> [xml-payload-here]

A failure call returns this:

<?xml version="1.0" encoding="utf-8" ?> <error code="[error-code]" message="[error-message]"

Error Codes
A complete list of error codes can be found here: http://wiki.xibo.org.uk/wiki/Error_codes

A list of the potential error codes from each method call can be found with the documentation of that call.

Methods
A list of transactions that we intend to support

Displays

 * DisplayList
 * DisplayEdit
 * DisplayRetire
 * DisplayDelete
 * DisplayUserGroupSecurity
 * DisplayUserGroupEdit

DisplayGroups

 * DisplayGroupList
 * DisplayGroupAdd
 * DisplayGroupEdit
 * DisplayGroupDelete
 * DisplayGroupMembersList
 * DisplayGroupMembersEdit
 * DisplayGroupUserGroupList
 * DisplayGroupUserGroupEdit

Layout

 * LayoutList
 * LayoutAdd
 * LayoutEdit
 * LayoutCopy
 * LayoutDelete
 * LayoutRetire
 * LayoutBackgroundList
 * LayoutBackgroundEdit
 * LayoutGetXlf
 * LayoutRegionList
 * LayoutRegionAdd
 * LayoutRegionEdit
 * LayoutRegionPosition
 * LayoutRegionTimelineList
 * LayoutRegionMediaAdd
 * LayoutRegionMediaReorder
 * LayoutRegionMediaDelete
 * LayoutRegionLibraryAdd
 * LayoutRegionMediaEdit
 * LayoutRegionMediaDetails

Library

 * LibraryMediaFileUpload
 * LibraryMediaFileRevise
 * LibraryMediaAdd
 * LibraryMediaEdit
 * LibraryMediaRetire
 * LibraryMediaDownload
 * LibraryMediaList

Schedule

 * ScheduleList
 * ScheduleAdd
 * ScheduleEdit
 * ScheduleDelete

Template

 * TemplateList
 * TemplateDelete

Resolution

 * ResolutionList

Modules

 * ModuleList

Other

 * Version
 * ServerStatus

= Method Calls = Currently supported transactions

Library
Transactions related to the Library

LibraryMediaFileUpload
Parameters
 * FileID - Null for 1st call
 * Chunk Offset
 * Check Sum (MD5)

Response
 * FileID
 * Offset (file length)

Errors
 * 1 - Access Denied
 * 2 - Payload Checksum doesn't match provided checksum
 * 3 - Unable to add File record to the Database
 * 4 - Library location does not exist
 * 5 - Unable to create file in the library location
 * 6 - Unable to write to file in the library location
 * 7 - File does not exist

LibraryMediaAdd
Parameters
 * fileId
 * type (image|video|flash|ppt)
 * name
 * duration
 * fileName (including extension)

Response
 * MediaID

Errors
 * Code 1 - Access Denied
 * Code 10 - The Name cannot be longer than 100 characters
 * Code 11 - You must enter a duration
 * Code 12 - This user already owns media with this name
 * Code 13 - Error inserting media into the database
 * Code 14 - Cannot clean up after failure
 * Code 15 - Cannot store file
 * Code 16 - Cannot update stored file location
 * Code 18 - Invalid File Extension

LibraryMediaEdit
Parameters
 * mediaId
 * name
 * duration

Response
 * success

Errors
 * 1 - Access Denied
 * 10 - The Name cannot be longer than 100 characters
 * 11 - You must enter a duration
 * 12 - This user already owns media with this name
 * 30 - Database failure updating media

LibraryMediaFileRevise
Parameters
 * mediaId
 * fileId
 * fileName (including extension)

Response
 * mediaId

Errors
 * 1 - Access Denied
 * 13 - Error inserting media into the database
 * 14 - Cannot clean up after failure
 * 15 - Cannot store file
 * 16 - Cannot update stored file location
 * 18 - Invalid File Extension
 * 31 - Unable to get information about existing media record
 * 32 - Unable to update existing media record

LibraryMediaRetire
Parameters
 * mediaId

Response
 * success

Error Codes
 * 1 - Access Denied
 * 19 - Error retiring media

LibraryMediaDelete
Parameters
 * mediaId

Response
 * Success = True

Error Codes
 * 1 - Access Denied
 * 20 - Cannot check if media is assigned to layouts
 * 21 - Media is in use
 * 22 - Cannot locate stored files, unable to delete
 * 23 - Database error deleting media

Layout
Transactions Related to Layouts

LayoutAdd
Parameters
 * layout - The Name of the Layout
 * description - The Description of the Layout
 * permissionid - PermissionID for the layout
 * tags - Tags for the Layout
 * templateid - Template for the Layout

Response
 * layout - The ID of the layout

Errors
 * Code 1 - Access Denied
 * Code 25001 - Layout Name must be between 1 and 50 characters
 * Code 25002 - Description must be less than 254 characters
 * Code 25003 - All tags combined must be less that 254 characters
 * Code 25004 - User already has a layout with this name
 * Code 25005 - Database error adding layout
 * Code 25006 - Failed to Parse Tags
 * Code 25007 - Unable to update layout xml
 * Code 25008 - Unable to Delete layout on failure

LayoutDelete
Parameters
 * layoutId - The ID of the layout to delete

Response
 * success = true

Errors
 * Code 1 - Access Denied
 * Code 25008 - Unable to delete layout

TemplateDelete
Parameters
 * templateId - The ID of the template to delete

Response
 * success = true

Errors
 * Code 1 - Access Denied
 * Code 25105 - Unable to delete template

LayoutRegionList
Parameters
 * layoutId

Response

A list of region timelines. Each item will have the following values:


 * regionid
 * width
 * height
 * top
 * left
 * ownerid
 * permission_edit
 * permission_del
 * permission_update_permissions

Error Codes
 * 1 - Access Denied

LayoutRegionAdd
Adds a new Region Timeline to a Layout

Parameters
 * layoutId
 * width
 * height
 * top
 * left
 * name

Response
 * success = true

Error Codes
 * 1 - Access Denied

LayoutRegionEdit
Edits an existing Region Timeline on a Layout

Parameters
 * layoutId
 * regionId
 * width
 * height
 * top
 * left
 * name

Response
 * success = true

Error Codes
 * 1 - Access Denied

LayoutRegionDelete
Deletes an existing Region Timeline on a Layout

Parameters
 * layoutId
 * regionId

Response
 * success = true

Error Codes
 * 1 - Access Denied

Layout Timelines
Transactions related to layout timelines

LayoutRegionTimelineList
Parameters
 * layoutId
 * regionId

Response

A list of media items on a region timeline. Each item will have the following values:


 * mediaid
 * lkid
 * type
 * duration
 * permission_edit
 * permission_del
 * permission_update_duration
 * permission_update_permissions

Error Codes
 * 1 - Access Denied

LayoutRegionMediaDetails
Parameters
 * layoutId
 * regionId
 * mediaId

Response The XLF for the provided media id (XML format)

Error Codes
 * 1 - Access Denied

LayoutRegionMediaAdd
Parameters
 * layoutId
 * regionId
 * type (the type of media item being added)
 * xlf (the xibo layout file xml representing the media to add)

The XLF will be checked for the attributes that are required for all media type. It is the callers responsibility to ensure media type specific attributes are set correctly.

Response The Media ID added

Error Codes
 * 1 - Access Denied

LayoutRegionLibraryAdd
Parameters
 * layoutId
 * regionId
 * mediaList (A list of media id's from the library that should be added to to supplied layout/region)

Response success (true|error)

Error Codes
 * 1 - Access Denied

LayoutRegionMediaEdit
Parameters
 * layoutId
 * regionId
 * mediaId
 * xlf (the xibo layout file xml representing the media to add)

The XLF will be checked for the attributes that are required for all media type. It is the callers responsibility to ensure media type specific attributes are set correctly.

Response success (true|error)

Error Codes
 * 1 - Access Denied

LayoutRegionMediaReorder
Parameters
 * layoutId
 * regionId
 * mediaList (array('mediaid' => '', 'lkid' => 0))

Response
 * success (true|false)

Error Codes
 * 1 - Access Denied

LayoutRegionMediaDelete
Parameters
 * layoutId
 * regionId
 * mediaId

Response success (true|error)

Error Codes
 * 1 - Access Denied

ModuleList
Response A list of modules with the following attributes:
 * module - The Module Name
 * layoutOnly- Whether the module is a library based module or only available for layouts
 * description - A description of the module
 * extensions - Extensions allowed by this module

Error Codes
 * 40 - Unable to query for modules

Version
Response <?xml version="1.0"?> <version app_ver="1.1.1" XlfVersion="1" XmdsVersion="2" DBVersion="22"/>