Difference between revisions of "XTS API"

From EUTC Wiki
m (→‎General Errors)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
== XTS Application Programming Interface ==
+
= XTS Application Programming Interface =
  
 
Correct (though incomplete) as of 2008-07-18 (RC1 "Fat Cat")
 
Correct (though incomplete) as of 2008-07-18 (RC1 "Fat Cat")
 +
 +
<br/><br/>
 +
= General Errors =
 +
These errors can occur when calling any command, or when calling a command incorrectly. Errors are returned as an [[#<error>]] document.
 +
* '''401 notAuthorised''' You are not authorised to perform the action. You may need to supply a password, or it might simply be impossible to do what you want to do from the machine you're on.
 +
* '''400.1 unrecognisedCommand''' The command is not recognised. Either you spelled it wrong, the API has changed since the documentation was written or you're simply doing it wrong.
 +
 +
<br/><br/>
 +
 +
= Commands =
  
 
== getshows ==
 
== getshows ==
Line 7: Line 17:
 
* No parameters (yet)
 
* No parameters (yet)
 
=== Returns ===
 
=== Returns ===
−
<shows> containing [[#<show>]]s representing all shows in the database.
+
A <shows> document containing [[#<showsummary>]]s representing all shows in the database.
 
=== Errors ===
 
=== Errors ===
 
* Never returns an error.
 
* Never returns an error.
Line 18: Line 28:
 
=== Errors ===
 
=== Errors ===
 
* '''404.3 showNotFound''' if the show doesn't exist in the database.
 
* '''404.3 showNotFound''' if the show doesn't exist in the database.
 +
 +
== getperformances ==
 +
=== Parameters ===
 +
* '''showid''' The ID of the show to get the performances of.
 +
=== Returns ===
 +
A <performances> document containing [[#<performance>]]s representing all performances for the specified show.
 +
=== Errors ===
 +
* '''404.3 showNotFound''' if the show doesn't exist in the database.
 +
 +
== getperformance ==
 +
=== Parameters ===
 +
* '''performanceid''' The ID of the performance to get.
 +
=== Returns ===
 +
A [[#<performance>]] representing the performance.
 +
=== Errors ===
 +
* '''404.2 performanceNotFound''' if the performance doesn't exist in the database.
 +
 +
 +
<br/><br/>
 +
= XML =
 +
 +
== <error> ==
 +
Details an error that occured while processing your request.
 +
=== Elements ===
 +
* '''@type''' The type number of the error, consists of a major and an (optional) minor part separated by a decimal point.
 +
* '''<message>''' A human-readable description of the error.
 +
=== Example ===
 +
<code xml>
 +
  <error type="400.1">
 +
    <message>Unrecognised command.</message>
 +
  </error>
 +
</code>
 +
 +
== <showsummary> ==
 +
Gives some summary details about a show in the database.
 +
=== Elements ===
 +
* '''<id>''' The ID of the show.
 +
* '''<name>''' The name of the show.
 +
* '''<tagline>''' The show's tagline / strapline / subtitle.
 +
=== Example ===
 +
<code xml>
 +
  <showsummary>
 +
    <id>1</id>
 +
    <name>Alice In Wonderland</name>
 +
    <tagline>Texas Woman's University</tagline>
 +
  </showsummary>
 +
</code>
 +
 +
== <show> ==
 +
A <show> tag describes a single show in the database.
 +
=== Elements ===
 +
* '''<id>''' The ID of the show.
 +
* '''<name>''' The name of the show.
 +
* '''<tagline>''' The show's tagline / strapline / subtitle.
 +
* '''<description>''' The show's description, if supplied. The usefulness of this field is debatable. I imagined it would carry publicity information that could be insta-formatted into web pages on the Bedlam Theatre website. Perhaps we should leave this tag as "reserved for future deprecation".
 +
=== Example ===
 +
<code xml>
 +
  <show>
 +
    <id>15</id>
 +
    <name>Assassins</name>
 +
    <tagline>Rather Like a Shark/DULOG</tagline>
 +
    <description/>
 +
  </show>
 +
</code>
 +
 +
== <performance> ==
 +
A <performance> tag describes a single performance in the database.
 +
=== Elements ===
 +
* '''<id>''' The ID of the performance.
 +
* '''<showid>''' The ID of the performance.
 +
* '''<start>''' The start time of the performance in seconds since the UNIX epoch.
 +
* '''<startdatetime>''' The human-readable start time of the performance.
 +
* '''<tickets>''' Ticket details incorporating:
 +
** '''<total>''' The total number of seats for the performance (ie the maximum number of tickets that can be sold).
 +
** '''<sold>''' The number of tickets that have been sold (net).
 +
** '''<booked>''' The number of tickets that are still booked (ie, awaiting collection).
 +
** '''<heldback>''' The number of tickets that are held back, ie, reserved for later sale.
 +
** '''<remaining>''' The number of tickets that are immediately available for sale.
 +
=== Example ===
 +
<code xml>
 +
  <performance>
 +
    <id>1</id>
 +
    <showid>1</showid>
 +
    <start>1217841300</start>
 +
    <startdatetime>2008-08-04 10:15</startdatetime>
 +
    <tickets>
 +
      <total>90</total>
 +
      <sold>0</sold>
 +
      <booked>1</booked>
 +
      <heldback>18</heldback>
 +
      <remaining>71</remaining>
 +
    </tickets>
 +
  </performance>
 +
</code>

Latest revision as of 17:34, 25 July 2008

XTS Application Programming Interface

Correct (though incomplete) as of 2008-07-18 (RC1 "Fat Cat")



General Errors

These errors can occur when calling any command, or when calling a command incorrectly. Errors are returned as an #<error> document.

  • 401 notAuthorised You are not authorised to perform the action. You may need to supply a password, or it might simply be impossible to do what you want to do from the machine you're on.
  • 400.1 unrecognisedCommand The command is not recognised. Either you spelled it wrong, the API has changed since the documentation was written or you're simply doing it wrong.



Commands

getshows

Parameters

  • No parameters (yet)

Returns

A <shows> document containing #<showsummary>s representing all shows in the database.

Errors

  • Never returns an error.

getshow

Parameters

  • showid The ID of the show to get.

Returns

A #<show> representing the show.

Errors

  • 404.3 showNotFound if the show doesn't exist in the database.

getperformances

Parameters

  • showid The ID of the show to get the performances of.

Returns

A <performances> document containing #<performance>s representing all performances for the specified show.

Errors

  • 404.3 showNotFound if the show doesn't exist in the database.

getperformance

Parameters

  • performanceid The ID of the performance to get.

Returns

A #<performance> representing the performance.

Errors

  • 404.2 performanceNotFound if the performance doesn't exist in the database.




XML

<error>

Details an error that occured while processing your request.

Elements

  • @type The type number of the error, consists of a major and an (optional) minor part separated by a decimal point.
  • <message> A human-readable description of the error.

Example

 <error type="400.1">
   <message>Unrecognised command.</message>
 </error>

<showsummary>

Gives some summary details about a show in the database.

Elements

  • <id> The ID of the show.
  • <name> The name of the show.
  • <tagline> The show's tagline / strapline / subtitle.

Example

 <showsummary>
   <id>1</id>
   <name>Alice In Wonderland</name>
   <tagline>Texas Woman's University</tagline>
 </showsummary>

<show>

A <show> tag describes a single show in the database.

Elements

  • <id> The ID of the show.
  • <name> The name of the show.
  • <tagline> The show's tagline / strapline / subtitle.
  • <description> The show's description, if supplied. The usefulness of this field is debatable. I imagined it would carry publicity information that could be insta-formatted into web pages on the Bedlam Theatre website. Perhaps we should leave this tag as "reserved for future deprecation".

Example

 <show>
   <id>15</id>
   <name>Assassins</name>
   <tagline>Rather Like a Shark/DULOG</tagline>
   <description/>
 </show>

<performance>

A <performance> tag describes a single performance in the database.

Elements

  • <id> The ID of the performance.
  • <showid> The ID of the performance.
  • <start> The start time of the performance in seconds since the UNIX epoch.
  • <startdatetime> The human-readable start time of the performance.
  • <tickets> Ticket details incorporating:
    • <total> The total number of seats for the performance (ie the maximum number of tickets that can be sold).
    • <sold> The number of tickets that have been sold (net).
    • <booked> The number of tickets that are still booked (ie, awaiting collection).
    • <heldback> The number of tickets that are held back, ie, reserved for later sale.
    • <remaining> The number of tickets that are immediately available for sale.

Example

 <performance>
   <id>1</id>
   <showid>1</showid>
   <start>1217841300</start>
   <startdatetime>2008-08-04 10:15</startdatetime>
   <tickets>
     <total>90</total>
     <sold>0</sold>
     <booked>1</booked>
     <heldback>18</heldback>
     <remaining>71</remaining>
   </tickets>
 </performance>

Retrieved from "http://wiki.friendsofbedlam.co.uk/index.php?title=XTS_API&oldid=3577"