Project APIFor purposes of this API description, all URLs are relative to the base url of http://localhost:8080/thalia Also, all data is in JSON format. A GET request will return JSON. A PUT or POST will submit a JSON document. To keep things simple, no authentication is required to access any resource. All use cases marked with [*] are not required as part of the final delivery for this project. The following abbreviations are used throughout this document:
Shows
Create show: POST /showsCreates a show instance and returns (in the body of the response) the ID of the show instance. NOTE: It would probably be better to have have an API where the show description is independent of the schedule of various instances of that show. 'Location' header with link to /shows/{wid} where {wid} is the newly assigned ID for the show instance. HTTP response code: 201 (Created) if everything is ok. 400 (Bad Request) if any of the required data is missing or is invalid. Resource URL/shows Parametersshow_info: Information about the show
seating_info: Sections and pricing
Example Request
Here is data being POST-ed
Example Response
Update show: PUT /shows/{wid}Updates the show instance identified by {wid}. The payload of the request replaces the existing resource. HTTP response code: 200 (OK). The body of the response will be empty. If the show instance identified by {wid} doesn't exist, then the HTTP response code will be 404 (Not Found). Resource URL/shows/{wid} Parametersshow_info: Information about the show
seating_info: Sections and pricing
Example Request
Here is data being PUT
Example ResponseThe body of the response is empty. View show: GET /shows/{wid}Returns detailed information about the show instance identified by {wid}. HTTP response code: 200 (OK) or 404 (Not found) if the show instance identified by {wid} doesn't exist. Resource URL/shows/{wid} ParametersNone. Example Request
Example Response
View all shows: GET /showsReturns an array of show instances. HTTP response code: 200 (OK). Resource URL/shows ParametersNone. Example Request
Example Response
View show sections: GET /shows/{wid}/sectionsReturns information about all sections in the theatre. HTTP response code: 200 (OK). Resource URL/sections ParametersNone. Example Request
Example Response
View show specific section: GET /shows/{wid}/sections/{sid}Returns specific seat availability in section {sid} for the show instance identified by {wid}. HTTP response code: 200 (OK). Resource URL/shows/{wid}/sections/{sid} ParametersNone. Example Request
Example Response
Subscribe to receive donated tickets: POST /shows/{wid}/donationsRequest tickets for the show identified by {wid}. 'Location' header with link to /shows/{wid}/donations/{did} where {did} is the ID assigned to the request. The body of the response will also contain {did}. HTTP response code: 201 (Created) if everything is ok. 400 (Bad Request) if any of the required data is missing or is invalid. Resource URL/shows/{wid}/donations Parameters
patron_info: Information about the patron and payment.
NOTE: a credit card is technically not required since the patron doesn't pay for donated tickets, however the owner of the theatre may want to have the info on file should she decide to charge patrons that have been assigned donated tickets but didn't use them. Example Request
Here is data being POST-ed
Example Response
View status of request for donated tickets: GET /shows/{wid}/donations/{did}Returns the status of the request, "pending" or "assigned" together with an array of ticket IDs, empty if the status is "pending", non-empty otherwise. HTTP response code: 200 (OK). 400 (Not found) if {wid} and/or {did} are invalid. Resource URL/shows/{wid}/donations/{did} ParametersNone. Example Request
Example Response
Another Example Response
Seating
Request seats auto: GET /seating?show={wid}§ion={sid}&count=[0-9]+[&starting_seat_id={cid}]Returns an array of "count" contiguous seats that are available in section {sid} for the show identified by {wid}. HTTP response code: 200 (OK). If "count" contiguous seats are not available in the section identified by {sid}, then return an error message. 404 (Not found) if {wid} and/or {sid} are invalid. Resource URL/seating Parameters
Example Request
Example Response
Another Example Request
Example Response
Example Request using starting_seat_id
Example Response
View all sections: GET /seatingReturns information about all sections in the theatre. HTTP response code: 200 (OK). Resource URL/seating ParametersNone. Example Request
Example Response
View specific section: GET /seating/{sid}Returns detailed information about the section identified by {sid}. HTTP response code: 200 (OK) or 404 (Not found) if the section identified by {sid} doesn't exist. Resource URL/seating/{sid} ParametersNone. Example Request
Example Response
Orders
Create order: POST /ordersCreates an order and returns (in the body of the response) the ID of the order and an array of tickets in the order. 'Location' header with link to /orders/{oid} where {oid} is the newly assigned ID for the order. HTTP response code: 201 (Created) if everything is ok. 400 (Bad Request) if any of the required data is missing or is invalid, or if one or more of the seats in the order request are no longer available. Resource URL/orders Parameters
patron_info: Information about the patron and payment.
Example Request
Here is data being POST-ed
Example Response
View all orders: GET /ordersReturns an array of all orders placed so far. HTTP response code: 200 (OK). Resource URL/orders ParametersNone. Example Request
Example Response
View orders by date: GET /orders?start_date=YYYYMMDD&end_date=YYYYMMDDReturns an array of all orders placed between the two dates. HTTP response code: 200 (OK). Resource URL/orders Parameters
Example Request
Example Response
View order: GET /orders/{oid}Returns detailed innformation about the order identified by {oid}. HTTP response code: 200 (OK). 404 (Not Found) if {oid} doesn't exist. Resource URL/orders/{oid} ParametersNone. Example Request
Example Response
Tickets
View ticket: GET /tickets/{tid}Returns detailed innformation about the ticket identified by {tid}. HTTP response code: 200 (OK). 404 (Not Found) if {tid} doesn't exist. Resource URL/tickets/{tid} ParametersNone. Example Request
Example Response
Scan ticket: POST /tickets/{tid}Changes the status of a ticket from "open" to "used". 'Location' header with link to /tickets/{tid} where {tid} is the ticket ID. HTTP response code: 200 (OK) if everything is ok. 400 (Bad Request) if any of the required data is missing or is invalid. Resource URL/tickets Parameters
Example Request
Here is data being POST-ed
Example Response
Donate tickets: POST /tickets/donationsDonates one or more tickets. The patron who initially created the order that includes donated tickets won't be able to use the donated tickets any more. 'Location' header with link to /orders/{oid} where {oid} is the order from which one or more tickets were donated. HTTP response code: 201 (Created) if everything is ok. 400 (Bad Request) if any of the required data is missing or is invalid. The body of the response is empty. Resource URL/tickets/donations Parameters
Example Request
Here is data being POST-ed
Reports
Get list of available reports: GET /reportsReturns an array of report IDs with their corresponding names. HTTP response code: 200 (OK). Resource URL/reports ParametersNone. Example Request
GET http://localhost:8080/thalia/reports
Example Response
[{
"mrid": "801",
"name": "Theatre occupancy"
}, {
"mrid": "802",
"name": "Revenue from ticket sales"
},
{
"mrid": "803",
"name": "Donated tickets report"
}
]
Get report: GET /reports/{mrid}[ ?show={wid} | ?start_date=YYYYMMDD&end_date=YYYYMMDD ]Returns the report identified by {mrid}. If no show ID ({wid}) is provided and no dates, then run the report for all shows and all dates. If a show ID is provided, then run the report just for that show. Alternately, instead of a show ID, a date range can be provided; in this case run the report for all shows that fall between the start_date and the end_date. HTTP response code: 200 (OK) or 404 (Not Found) if {mrid} [or {wid} or both] is invalid. Resource URL/report/{mrid} Parameters{mrid} (required): the ID of the report to be generated. {wid} (optional): the ID of the show for which the report is to be generated. start_date (optional): the start date for the date range of the report. end_date (optional): the end date for the date range of the report. Example Request
GET http://localhost:8080/thalia/reports/801
Example Response
{
"mrid": "801",
"name": "Occupancy report",
"start_date": "",
"end_date": "",
"total_shows": 3,
"total_seats": 255,
"sold_seats": 179,
"overall_occupancy": "70.1%",
"shows": [{
"wid": "307",
"show_info": {
"name": "King Lear",
"web": "http://www.example.com/shows/king-lear",
"date": "2017-12-04",
"time": "19:00"
},
"seats_available": 102,
"seats_sold": 91,
"occupancy": "89.2%"
},
{
"wid": "308",
"show_info": {
"name": "King Lear",
"web": "http://www.example.com/shows/king-lear",
"date": "2017-12-05",
"time": "13:00"
},
"seats_available": 51,
"seats_sold": 5,
"occupancy": "9.8%"
},
{
"wid": "309",
"show_info": {
"name": "King Lear",
"web": "http://www.example.com/shows/king-lear",
"date": "2017-12-05",
"time": "19:00"
},
"seats_available": 102,
"seats_sold": 83,
"occupancy": "81.3%"
}
]
}
Another Example Request
GET http://localhost:8080/thalia/reports/802?show=308
Example Response
{
"mrid": "802",
"name": "Revenue from ticket sales",
"start_date": "",
"end_date": "",
"total_shows": 1,
"total_seats": 51,
"sold_seats": 5,
"overall_revenue": 360,
"shows": [{
"wid": "308",
"show_info": {
"name": "King Lear",
"web": "http://www.example.com/shows/king-lear",
"date": "2017-12-05",
"time": "13:00"
},
"sections": [{
"sid": "123",
"section_name": "Front right",
"section_price": 60,
"seats_available": 16,
"seats_sold": 1,
"section_revenue": 60
},
{
"sid": "124",
"section_name": "Front center",
"section_price": 75,
"seats_available": 19,
"seats_sold": 4,
"section_revenue": 300
},
{
"sid": "125",
"section_name": "Front left",
"section_price": 60,
"seats_available": 16,
"seats_sold": 0,
"section_revenue": 0
}
]
}]
}
One More Example Request
GET http://localhost:8080/thalia/reports/803?start_date=20171201&end_date=20171231
Example Response
{
"mrid": "803",
"name": "Donated tickets report",
"start_date": "20171201",
"end_date": "20171231",
"total_shows": 3,
"total_seats": 255,
"sold_seats": 179,
"donated_tickets": 5,
"donated_and_used_tickets": 4,
"donated_and_used_value": 220,
"shows": [{
"wid": "307",
"show_info": {
"name": "King Lear",
"web": "http://www.example.com/shows/king-lear",
"date": "2017-12-04",
"time": "19:00"
},
"seats_available": 102,
"seats_sold": 91,
"donated_tickets": 3,
"donated_and_used_tickets": 2,
"donated_and_used_value": 100
},
{
"wid": "308",
"show_info": {
"name": "King Lear",
"web": "http://www.example.com/shows/king-lear",
"date": "2017-12-05",
"time": "13:00"
},
"seats_available": 51,
"seats_sold": 5,
"donated_tickets": 2,
"donated_and_used_tickets": 2,
"donated_and_used_value": 120
},
{
"wid": "309",
"show_info": {
"name": "King Lear",
"web": "http://www.example.com/shows/king-lear",
"date": "2017-12-05",
"time": "19:00"
},
"seats_available": 102,
"seats_sold": 83,
"donated_tickets": 0,
"donated_and_used_tickets": 0,
"donated_and_used_value": 0
}
]
}
Search
Search: GET /search?topic=topicword&key=keywordReturns all entities within the "topic" ("topicword" can be one of "show", "order") that match the "key" ("keyword" is a single word string, e.g. "bob", "King", etc.) HTTP response code: 200 (OK), or 404 if "topicword" has a value that's not allowed. Resource URL/search?topic=topicword&key=keyword Parameterstopic (required): the topic for search. The value for topic can be any of "show", "order". key (required): the search key. Anything that matches the keyword (the value of key) will be included in the result set. The search is case insensitive. If keyword is empty, then match everything. Example Request
Example Response
Here is an example with the "order" topic; in this example the match is on the order ID. Example Request
Example Response
One more example with the "order" topic; in this case the match is on the name of the patron. Example Request
Example Response
$Id: project-api.html,v 1.14 2017/11/09 21:36:08 virgil Exp $ |