Project APIThe general structure of API calls is: VERB [base]/[type]/[id]{?...}The VERB represents the verb used in the interaction, e.g. GET, PUT, POST. Content surrounded by [] is mandatory and will be replaced by the string literal identified. Possible insertion values:
Content surrounded by {} is optional. The Service Base URL takes the form of http(s)://server{/path} The path portion is optional, and does not include a trailing slash. Each resource type defined in this specification has a manager (or "entity set") that lives at the address /[type] where the [type] is the name of the resource type. For instance, the resource manager for the type parks will be found at: https://server/path/parks For purposes of this API description, the path will be parkpay. Let's say that you deploy your application in a tomcat container hosted locally, on your computer, and that tomcat has the default settings which means it will listen for requests at port 8080. The Service Base URL in this case is http://localhost:8080/parkpay. The resource manager for the type parks will be found at: http://localhost:8080/parkpay/parks. 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. To make examples easier to read we'll be using the following abbreviations throughout this document, instead of single generic id:
The following section show the resource sets and, for each of them the use cases implemented. NOTE" "search" is not exactly a resource set, however it is a valid end point for the API and it is needed to implement the search functionality as described in the requirements.
parks
Create parkPOST /parksCreates a park and returns (in the body of the response) the ID of the park. 'Location' header with link to /parks/[pid] where [pid] is the newly assigned ID for the park. HTTP response code:
Resource URL/parks Parameterslocation_info: Information about the park
Payment_info: Payment required for various vehicle classes.
Example Request
POST http://localhost:8080/parkpay/parks
Here is data being POST-ed
{
"location_info": {
"name": "Apple River Canyon",
"region": "Northwestern Illinois",
"address": "8763 E. Canyon Rd, Apple River, IL 61001",
"phone": "",
"web": "https://www.dnr.illinois.gov/Parks/Pages/AppleRiverCanyon.aspx",
"geo": { "lat": 42.448, "lng": -90.043 }
},
"payment_info": {
"motorcycle": [5, 8],
"car": [7, 9],
"rv": [10,13]
}
}
Example Response
{
"pid": "123"
}
Example Response when Something Went WrongLet's assume that the following data is being POST-ed
{
"location_info": {
"name": "Apple River Canyon",
"address": "8763 E. Canyon Rd, Apple River, IL 61001",
"phone": "815-745-3302",
"web": "https://www.dnr.illinois.gov/Parks/Pages/AppleRiverCanyon.aspx"
},
"payment_info": {
"motorcycle": [5, 8],
"car": [7, 10],
"rv": [10,13]
}
}
In this case the response body will look like this:
{
"type": "http://cs.iit.edu/~virgil/cs445/project/api/problems/data-validation",
"title": "Your request data didn't pass validation",
"detail": "Geo information is required but missing in your request",
"status": 400,
"instance": "/parks"
}
Update parkPUT /parks/[pid]Updates the park identified by [pid]. HTTP response codes:
Resource URL/parks/[pid] Parameterslocation_info: Information about the park
Payment_info: Payment required for various vehicle classes. NOTE: all payment data must be positive numbers or zero.
Example Request
PUT http://localhost:8080/parkpay/parks/123
Here is data being PUT
{
"location_info": {
"name": "Apple River Canyon",
"region": "Northwestern Illinois",
"address": "8763 E. Canyon Rd, Apple River, IL 61001",
"phone": "815-745-3302",
"web": "https://www.dnr.illinois.gov/Parks/Pages/AppleRiverCanyon.aspx",
"geo": { "lat": 42.448, "lng": -90.043 }
},
"payment_info": {
"motorcycle": [5, 8],
"car": [7, 10],
"rv": [10, 13]
}
}
Example Successful ResponseThe body of the response is empty. Example Response when Something Went WrongLet's assume that the following data is being PUT
{
"location_info": {
"name": "Apple River Canyon",
"region": "Northwestern Illinois",
"address": "8763 E. Canyon Rd, Apple River, IL 61001",
"phone": "815-745-3302",
"web": "https://www.dnr.illinois.gov/Parks/Pages/AppleRiverCanyon.aspx",
"geo": { "lat": 42.448, "lng": -90.043 }
},
"payment_info": {
"motorcycle": [5, -3],
"car": [7, 10],
"rv": [10, 13]
}
}
In this case the response body will look like this:
{
"type": "http://cs.iit.edu/~virgil/cs445/project/api/problems/data-validation",
"title": "Your request data didn't pass validation",
"detail": "All payment data must be a number greater than or equal to zero",
"status": 400,
"instance": "/parks/123"
}
Delete parkDELETE /parks/[pid]Deletes the park identified by [pid]. HTTP response codes:
Resource URL/parks/[pid] ParametersNone Example Request
DELETE http://localhost:8080/parkpay/parks/123
Example Successful ResponseThe body of the response is empty. View all parksGET /parksReturns a JSON array with all parks. HTTP response codes:
Resource URL/parks ParametersNone Example Request
GET http://localhost:8080/parkpay/parks
Example Successful Response
[{
"pid": 123,
"location_info": {
"name": "Apple River Canyon",
"region": "Northwestern Illinois",
"address": "8763 E. Canyon Rd, Apple River, IL 61001",
"phone": "815-745-3302",
"web": "https://www.dnr.illinois.gov/Parks/Pages/AppleRiverCanyon.aspx",
"geo": { "lat": 42.448, "lng": -90.043 }
}
},
{
"pid": 124,
"location_info": {
"name": "Castle Rock",
"region": "Northwestern Illinois",
"address": "1365 W. Castle Rd, Oregon IL 61061",
"phone": "815-732-7329",
"web": "https://www.dnr.illinois.gov/Parks/Pages/CastleRock.aspx",
"geo": { "lat": 41.978, "lng": -89.364 }
}
},
{
"pid": 131,
"location_info": {
"name": "Mermet Lake",
"region": "Southern Illinois",
"address": "1812 Grinnell Road, Belknap, IL 62908",
"phone": "618-524-5577",
"web": "https://www.dnr.illinois.gov/Parks/Pages/MermetLake.aspx",
"geo": { "lat": 37.275, "lng": -88.849 }
}
}
]
View park detailGET /parks/[pid]Get detailed information about the park identified by [pid]. HTTP response codes:
Resource URL/parks/[pid] ParametersNone Example Request
GET http://localhost:8080/parkpay/parks/124
Example Successful Response
{
"pid": 124,
"location_info": {
"name": "Castle Rock",
"region": "Northwestern Illinois",
"address": "1365 W. Castle Rd, Oregon IL 61061",
"phone": "815-732-7329",
"web": "https://www.dnr.illinois.gov/Parks/Pages/CastleRock.aspx",
"geo": { "lat": 41.978, "lng": -89.364 }
},
"payment_info": {
"motorcycle": [2, 3],
"car": [4.50, 7],
"rv": [7, 9.25]
}
}
Search parksGET /parks?key=keywordReturns an array of summary park information for the parks that match the search criteria. HTTP response codes:
Resource URL/parks Parameters
Example Request
GET http://localhost:8080/parkpay/parks?key=south
Example Response
[
{
"pid": 131,
"location_info": {
"name": "Mermet Lake",
"region": "Southern Illinois",
"address": "1812 Grinnell Road, Belknap, IL 62908",
"phone": "618-524-5577",
"web": "https://www.dnr.illinois.gov/Parks/Pages/MermetLake.aspx",
"geo": { "lat": 37.275, "lng": -88.849 }
}
}
]
View all notes associated with parkGET /parks/[pid]/notesGet an array of summary information for notes associated with the park identified by [pid]. HTTP response codes:
Resource URL/parks/[pid]/notes ParametersNone Example Request
GET http://localhost:8080/parkpay/parks/124/notes
Example Response
[{
"nid": 311,
"date": "2018-07-03",
"title": "No campground"
},
{
"nid": 583,
"date": "2018-08-02",
"title": "Great fishing"
}
]
View note associated with parkGET /parks/[pid]/notes/[nid]Get note [nid] associated with the park identified by [pid]. HTTP response codes:
Resource URL/parks/[pid]/notes/[nid] ParametersNone Example Request
GET http://localhost:8080/parkpay/parks/124/notes/583
Example Response
{
"nid": 583,
"pid": 124,
"vid": 447,
"date": "2018-08-02",
"title": "Great fishing",
"text": "Caught a walleye here, did't really expect anything other than catfish."
}
Create note and associate with parkPOST /parks/[pid]/notesCreates a note and associates it with park [pid]. Returns (in the body of the response) the ID of the note. 'Location' header with link to /notes/[nid] where [nid] is the ID for the newly created note. HTTP response code:
Resource URL/parks/[pid]/notes Parameters
Example Request
POST http://localhost:8080/parkpay/parks/124/notes
Here is data being POST-ed
{
"vid": 411,
"title": "No campground",
"text": "This place is beautiful, too bad that there is no campground here."
}
Example Response
{
"nid": "311"
}
Example Response when Something Went WrongLet's assume that the following data is being POST-ed
{
"vid": 412,
"title": "Mosquitos galore",
"text": "This is a nice place with good fihsing, but this year the mosquitos are killing us."
}
and that the visitor 412 never really paid for entrance to park 124. In this case the response body will look like this:
{
"type": "http://cs.iit.edu/~virgil/cs445/project/api/problems/data-validation",
"title": "Your request data didn't pass validation",
"detail": "You may not post a note to a park unless you paid for admission at that park",
"status": 400,
"instance": "/parks/124"
}
notes
View all notesGET /notesGet an array of summary information for all notes. HTTP response codes:
Resource URL/notes ParametersNone Example Request
GET http://localhost:8080/parkpay/notes
Example Response
[
{
"pid": 123,
"notes": [
{
"nid": 317,
"date": "2018-07-04",
"title": "Mosquitos galore"
}
]
},
{
"pid": 124,
"notes": [
{
"nid": 311,
"date": "2018-07-03",
"title": "No campground"
},
{
"nid": 583,
"date": "2018-08-02",
"title": "Great fishing"
}
]
}
]
View noteGET /notes/[nid]Get note [nid]. HTTP response codes:
Resource URL/notes/[nid] ParametersNone Example Request
GET http://localhost:8080/parkpay/notes/317
Example Response
{
"nid": 317,
"pid": 123,
"vid": 412,
"date": "2018-07-04",
"title": "Mosquitos galore",
"text": "This is a nice place with good fihsing, but this year the mosquitos are killing us."
}
Update notePUT /notes/[nid]Updates note [nid]. HTTP response code:
Resource URL/notes/[nid] Parameters
Example Request
PUT http://localhost:8080/parkpay/notes/317
Here is data being POST-ed
{
"vid": 412,
"title": "Mosquitos galore",
"text": "This is a nice place with good fishing, but this year the mosquitos are killing us."
}
Example ResponseThe body of the response is empty. Search notesGET /notes?key=keywordReturns an array of summary notes information for the notes that match the search criteria. HTTP response codes:
Resource URL/notes Parameters
Example Request
GET http://localhost:8080/parkpay/notes?key=FISH
Example Response
[
{
"pid": 123,
"notes": [
{
"nid": 317,
"date": "2018-07-04",
"title": "Mosquitos galore"
}
]
},
{
"pid": 124,
"notes": [
{
"nid": 583,
"date": "2018-08-02",
"title": "Great fishing"
}
]
}
]
orders
Create orderPOST /ordersCreates an order and returns (in the body of the response) the ID of the order. 'Location' header with link to /orders/[oid] where [oid] is the newly assigned ID for the order. HTTP response code:
Resource URL/orders Parameterspid (required): The ID of the park. vehicle (required): Detailed information about the vehicle the payment (order) is for.
visitor (required): Information about the visitor.
Example Request
POST http://localhost:8080/parkpay/orders
Here is data being POST-ed
{
"pid": 124,
"vehicle": {
"state": "IL",
"plate": "GOCUBS",
"type": "car"
},
"visitor": {
"name": "John Doe",
"email": "john.doe@example.com",
"payment_info": {
"card": "4388567890987654",
"name_on_card": "John Doe",
"expiration_date": "12/19",
"zip": 60616
}
}
}
Example Response
{
"oid": "751"
}
Example Request
POST http://localhost:8080/parkpay/orders
Here is another example if data being POST-ed
{
"pid": 124,
"vehicle": {
"state": "CA",
"plate": "60MPG",
"type": "rv"
},
"visitor": {
"name": "",
"email": "jane.smith@example.com",
"payment_info": {
"card": "373456789045678",
"name_on_card": "Jane Smith",
"expiration_date": "05/23",
"zip": 94102
}
}
}
Example Response
{
"oid": "761"
}
Example Response when Something Went WrongLet's assume that the following data is being POST-ed and that the credit card processor decides to decline the transaction. Everything looks good as far as submitted data goes, so you don't have any validation errors, but that's not enough for a credit/debit transaction to go through.
{
"pid": 124,
"vehicle": {
"state": "CA",
"plate": "60MPG",
"type": "rv"
},
"visitor": {
"name": "",
"email": "jane.smith@example.com",
"payment_info": {
"card": "373456789074007",
"name_on_card": "Jane Smith",
"expiration_date": "05/23",
"zip": 94102
}
}
}
In this case the response body may look like this:
{
"type": "http://cs.iit.edu/~virgil/cs445/project/api/problems/processing-errors",
"title": "There has been an error processing your request.",
"detail": "Credit card transaction declined.",
"status": 400,
"instance": "/orders"
}
View all ordersGET /ordersGet an array of summary information for all orders. HTTP response codes:
Resource URL/notes ParametersNone Example Request
GET http://localhost:8080/parkpay/orders
Example Response
[
{
"oid": 751,
"pid": 124,
"date": "2018-07-03",
"type": "car",
"amount": 4.50
},
{
"oid": 761,
"pid": 124,
"date": "2018-08-02",
"type": "rv",
"amount": 9.25
},
{
"oid": 757,
"pid": 123,
"date": "2018-07-04",
"type": "car",
"amount": 10
},
{
"oid": 773,
"pid": 123,
"date": "2018-08-05",
"type": "rv",
"amount": 13
}
]
View orderGET /orders/[oid]Get order [oid]. HTTP response codes:
Resource URL/notes/[oid] ParametersNone Example Request
GET http://localhost:8080/parkpay/orders/751
Example Response
{
"oid": 751,
"pid": 123,
"amount": 4.50,
"vid": 411,
"date": "2018-07-03",
"vehicle": {
"state": "IL",
"plate": "GOCUBS",
"type": "car"
},
"visitor": {
"name": "John Doe",
"email": "john.doe@example.com",
"payment_info": {
"card": "xxxxxxxxxxxx7654",
"name_on_card": "John Doe",
"expiration_date": "12/19",
"zip": 60616
}
},
"payment_processing": {
"card_transaction_id": "123-4567-89",
"date_and_time": "2018-07-03T15:28:56.782Z"
}
}
Search ordersGET /orders?key=keywordReturns an array of summary order information for the orders that match the search criteria. HTTP response codes:
Resource URL/orders Parameters
Example Request
GET http://localhost:8080/parkpay/orders?key=60MPG
Example Response
[
{
"oid": 761,
"pid": 124,
"date": "2018-08-02",
"type": "rv",
"amount": 9.25
},
{
"oid": 773,
"pid": 123,
"date": "2018-08-05",
"type": "rv",
"amount": 13
}
]
Another Example Request
GET http://localhost:8080/parkpay/orders?key=john.doe
Example Response
[
{
"oid": 751,
"pid": 124,
"date": "2018-07-03",
"type": "car",
"amount": 4.50
}
]
visitors
View all visitorsGET /visitorsGet an array of summary information for all visitors. HTTP response codes:
Resource URL/visitors ParametersNone Example Request
GET http://localhost:8080/parkpay/visitors
Example Response
[
{
"vid": 411,
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"vid": 412,
"name": "John Q. Public",
"email": "jqpublic@example.com"
},
{
"vid": 447,
"name": "Jane Smith",
"email": "jane.smith@example.com"
}
]
View visitorGET /visitors/[vid]Get visitor [vid] and order history. HTTP response codes:
Resource URL/visitors/[vid] ParametersNone Example Request
GET http://localhost:8080/parkpay/visitors/447
Example Response
{
"vid": 447,
"visitor": {
"name": "Jane Smith",
"email": "jane.smith@example.com"
},
"orders": [{
"oid": 761,
"pid": 124,
"date": "2018-08-02"
},
{
"oid": 773,
"pid": 123,
"date": "2018-08-05"
}
],
"notes": [{
"nid": 583,
"pid": 124,
"date": "2018-08-02",
"title": "Great fishing"
}]
}
Search visitorsGET /visitors?key=keywordReturns an array of summary visitor information that match the search criteria. HTTP response codes:
Resource URL/visitors Parameters
Example Request
GET http://localhost:8080/parkpay/visitors?key=John
Example Response
[
{
"vid": 411,
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"vid": 412,
"name": "John Q. Public",
"email": "jqpublic@example.com"
}
]
reports
View all reportsGET /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/parkpay/reports
Example Response
[{
"rid": 907,
"name": "Admissions report"
}, {
"mrid": 911,
"name": "Revenue report"
}
]
Get reportGET /reports/[rid]{?start_date=YYYYMMDD&end_date=YYYYMMDD}Returns the report identified by [rid]. If no dates are provided, then include all admissions you have in the system. If a start_date is provided and no end_date, then include all admissions on the start_date and after. If only the end_date is specified, then include all admissions prior to and on the end_date. Finally, if both the start_date and end_date are provided, then only include admissions in that range (including admissions on the start and dates). The report must include all parks. HTTP response codes:
Resource URL/reports/[rid] Parameters
Example Request
GET http://localhost:8080/parkpay/reports/907
Example Response
{
"rid": 907,
"name": "Admissions report",
"start_date": "",
"end_date": "",
"total_admissions": 4,
"detail_by_park": [{
"pid": 123,
"name": "Apple River Canyon",
"admissions": 2
},
{
"pid": 124,
"name": "Castle Rock",
"admissions": 2
},
{
"pid": 131,
"name": "Mermet Lake",
"admissions": 0
}
]
}
Another Example Request
GET http://localhost:8080/parkpay/reports/911?start_date=20180701&end_date=20180731
Example Response
{
"rid": 911,
"name": "Revenue report",
"start_date": "2018-08-01",
"end_date": "2018-08-31",
"total_orders": 2,
"total_revenue": 22.25,
"detail_by_park": [{
"pid": 123,
"name": "Apple River Canyon",
"orders": 1,
"revenue": 13.00
},
{
"pid": 124,
"name": "Castle Rock",
"orders": 1,
"revenue": 9.25
},
{
"pid": 131,
"name": "Mermet Lake",
"orders": 0,
"revenue": 0.00
}
]
}
search
SearchGET /search?key=keyword{&start_date=YYYYMMDD&end_date=YYYYMMDD}Returns an array that includes all parks, orders, visitors, notes that match the keyword. The start and end dates are used to filter out matches that fall outside the data range. If a start_date is provided and no end_date, then include all search results on the start_date and after. If only the end_date is specified, then include all search results prior to and on the end_date. HTTP response codes:
Resource URL/search Parameters
Example Request
GET http://localhost:8080/parkpay/search?key=&start_date=20180802&end_date=20180802
Example Response
|