Project API

The 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:

  • base is the Service Base URL which is the address where all of the resources defined by this API are found.
  • type is generally the name of a resource type, e.g. "rides".
  • id is the logical id of a resource, and will be generated by your application when a resource is created. NOTE: we'll be using POST to create new resources; we could use PUT as well to create new resources however, in this case, we would have to provide a unique identifier for the resource being created.

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 rides will be found at: https://server/path/rides

For purposes of this API description, the path will be sar.

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/sar. The resource manager for the type rides will be found at: http://localhost:8080/sar/rides.

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 and understand the API, we'll be using the following abbreviations throughout this document, instead of single generic id:

  • rid: ride ID
  • mid: message ID
  • aid: account ID
  • pid: report ID
  • sid: rating ID
  • jid: join ride request ID

The following sections 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.

Also, you may want to check the Known Limitations section of this document that documents discrepancies between the requirements and the API.

accounts

^Top^ ^rides^

Create account

POST /accounts

Creates an account and returns (in the body of the response) the ID of the account.

'Location' header with link to /accounts/[aid] where [aid] is the newly assigned ID for the ride.

HTTP response code:

  • 201 (Created) if everything is ok.
  • 400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.

Resource URL

/accounts

Parameters

first_name (required): first name of the account holder.

last_name (required): last name of the account holder.

phone: mobile phone number.

picture: for simplicity we'll just use a URL here.

is_active: account's status, true if active, false otherwise.

Example Request

      POST http://localhost:8080/sar/accounts

Here is data being POST-ed 

      {
      	"first_name": "John",
      	"last_name": "Smith",
      	"phone": "312-456-7890",
      	"picture": "http://example.com/images/john-smith.jpeg",
        "is_active": false
      }

Example Response

      {
        "aid": 19
      }

Example Response when Something Went Wrong

Let's assume that the following data is being POST-ed 

      {
      	"first_name": "John",
      	"last_name": "Smith",
      	"phone": "312-456-789O",
      	"picture": "http://example.com/images/john-smith.jpeg",
        "is_active": false
      }

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": "Invalid phone number",
        "status": 400,
        "instance": "/accounts"
      }

^Top^ ^accounts^

Activate account

PUT /accounts/[aid]/status

Activates the account identified by [aid].

NOTE: we could use a PATCH and only update the value of is_active. However, PATCH is not idempotent.

HTTP response code:

  • 204 (No content) if everything is ok.
  • 400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
  • 404 (Not found) the account identified by [aid] doesn't exist.

Resource URL

/accounts/[aid]/status

Parameters

first_name (required): first name of the account holder.

last_name (required): last name of the account holder.

phone: mobile phone number.

picture: for simplicity we'll just use a URL here.

is_active: set the value to true for the account to become active.

Example Request

      PUT http://localhost:8080/sar/accounts/19/status

Here is data being PUT: 

      {
      	"first_name": "John",
      	"last_name": "Smith",
      	"phone": "312-456-7890",
      	"picture": "http://example.com/images/john-smith.jpeg",
        "is_active": true
      }

Example Response

The body of the response is empty.

Example Response when Something Went Wrong

Let's assume that the following data is being POST-ed 

      {
      	"first_name": "John",
      	"last_name": "Smith",
      	"phone": "312-456-7890",
      	"picture": "http://example.com/images/john-smith.jpeg",
        "is_active": false
      }

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": "Invalid value for is_active",
        "status": 400,
        "instance": "/accounts/19/status"
      }

^Top^ ^accounts^

Update account

PUT /accounts/[aid]

Updates the account identified by [aid].

HTTP response codes:

  • 204 (No content) if everything is ok.
  • 400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
  • 404 (Not found) the account identified by [aid] doesn't exist.

Resource URL

/accounts/[aid]

Parameters

first_name (required): first name of the account holder.

last_name (required): last name of the account holder.

phone: mobile phone number.

picture: for simplicity we'll just use a URL here.

Example Request

      PUT http://localhost:8080/sar/accounts/19

Here is the data being PUT 

      {
      	"first_name": "John",
      	"last_name": "Smith",
      	"phone": "312-456-7809",
      	"picture": "http://example.com/images/john-smith.jpeg",
        "is_active": false
      }

Example Successful Response

The body of the response is empty.

Example Response when Something Went Wrong

Let's assume that the following data is being PUT 

      {
      	"first_name": "John",
      	"last_name": "12345",
      	"phone": "312-456-789O",
      	"picture": "http://example.com/images/john-smith.jpeg",
        "is_active": false
      }

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": "The last name appears to be invalid.",
        "status": 400,
        "instance": "/accounts/19"
      }

Another Example Response when Something Went Wrong

Let's assume that the following data is being PUT 

      {
      	"first_name": "John",
      	"last_name": "Smith",
      	"phone": "312-456-789O",
      	"picture": "http://example.com/images/john-smith.jpeg",
        "is_active": true
      }

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": "Invalid value for is_active",
        "status": 400,
        "instance": "/accounts/19"
      }

^Top^ ^accounts^

Delete account

DELETE /accounts/[aid]

Deletes the account identified by [aid].

NOTE: deleting entities can be very difficult, in particular when there are other entities referencing the resource being deleted. For example, what happens with all the rides an accpount has created when the account itself is deleted?

HTTP response codes:

  • 204 (No content) if the entity has been removed and there is no additional information in the body of the response.
  • 404 (Not found) if the account identified by [aid] doesn't exist.

Resource URL

/accounts/[aid]

Parameters

None

Example Request

      DELETE http://localhost:8080/sar/accounts/19

Example Successful Response

The body of the response is empty.

^Top^ ^accounts^

View all accounts

GET /accounts

Returns a JSON array with all accounts.

HTTP response codes:

  • 200 (OK).

Resource URL

/accounts

Parameters

None

Example Request

      GET http://localhost:8080/sar/accounts

Example Successful Response

      [{
      		"aid": 19,
      		"name": "John Smith",
      		"date_created": "3-Mar-2020, 08:13:57",
      		"is_active": true
      	},
      	{
      		"aid": 67,
      		"name": "Jane Doe",
      		"date_created": "4-Mar-2020, 19:59:00",
      		"is_active": false
      	}
      ]

^Top^ ^accounts^

(*) View account detail

GET /accounts/[aid]

Get detailed information about the account identified by [aid].

NOTE: there is no use case in the requirements that requires this functionality.

^Top^ ^accounts^

Search accounts

GET /accounts?key=keyword

Returns an array of summary account information for the accounts that match the keyword.

HTTP response codes:

  • 200 (OK).

Resource URL

/accounts

Parameters

key (required): the origin of a ride. Any account that has a first or last name, or phone number that matches "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

      GET http://localhost:8080/sar/accounts?key=

Example Response

      [{
      		"aid": 19,
      		"name": "John Smith",
      		"date_created": "3-Mar-2020, 08:13:57",
      		"is_active": true
      	},
      	{
      		"aid": 67,
      		"name": "Jane Doe",
      		"date_created": "4-Mar-2020, 19:59:00",
      		"is_active": false
      	}
      ]

Another Example Request

      GET http://localhost:8080/sar/accounts?key=smith

Example Response

      [{
      		"aid": 19,
      		"name": "John Smith",
      		"date_created": "3-Mar-2020, 08:13:57",
      		"is_active": true
      	}
      ]

^Top^ ^accounts^

Rate account

POST /accounts/[aid]/ratings

Rate the account identified by [aid] and return (in the body of the response) the ID of the account, [sid].

'Location' header with link to /accounts/[aid]/ratings/[sid] where [sid] is the newly assigned ID for the rating.

HTTP response code:

  • 201 (Created) if everything is ok.
  • 400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.

Resource URL

/accounts/[rid]/ratings

Parameters

rid (required): the ride for which the rating is given.

sent_by_id (required): the account ID doing the rating; it must be either the creator of the ride, or a rider on that ride.

rating (required): an integer between 1 and 5.

comment: a comment made by the driver (creator of the ride) about the passenger (the rider), or by the rider about the driver.

Example Request

      POST http://localhost:8080/sar/accounts/19/ratings

Here is data being POST-ed 

      {
      	"rid": 47,
      	"sent_by_id": 67,
      	"rating": 5,
        "comment": "John was punctual and the ride was great."
      }

Example Response

      {
        "sid": 31
      }

Example Response when Something Went Wrong

Let's assume that the following data is being POST-ed 

      {
      	"rid": 47,
      	"sent_by_id": 70,
      	"rating": 5,
        "comment": "Blah."
      }

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": "This account (70) did't create this ride (47) nor was it a passenger",
        "status": 400,
        "instance": "/accounts/19/ratings"
      }

^Top^ ^accounts^

View driver ratings

GET /accounts/[aid]/driver

Returns a JSON array with all ratings given to [aid] as a driver.

HTTP response codes:

  • 200 (OK).

Resource URL

/accounts/[aid]/driver

Parameters

None

Example Request

      GET http://localhost:8080/sar/accounts/19/driver

Example Successful Response

      {
      	"aid": 19,
      	"first_name": "John",
      	"rides": 3,
      	"ratings": 2,
      	"average_rating": 4.5,
      	"detail": [{
      			"rid": 47,
      			"sent_by_id": 71,
      			"first_name": "Bob",
      			"date": "13-Apr-2020",
      			"rating": 5,
      			"comment": "Great car, smooth drive, very good conversation."
      		},
      		{
      			"rid": 43,
      			"sent_by_id": 83,
      			"first_name": "Alice",
      			"date": "1-Apr-2020",
      			"rating": 4,
      			"comment": "John drives too fast, I was scared out of my mind."
      		}
      	]
      }

^Top^ ^accounts^

View rider ratings

GET /accounts/[aid]/rider

Returns a JSON array with all ratings given to [aid] as a rider (passenger).

HTTP response codes:

  • 200 (OK).

Resource URL

/accounts/[aid]/rider

Parameters

None

Example Request

      GET http://localhost:8080/sar/accounts/67/rider

Example Successful Response

      {
      	"aid": 67,
      	"first_name": "Jane",
      	"rides": 1,
      	"ratings": 1,
      	"average_rating": 5,
      	"detail": [{
      		"rid": 123,
      		"sent_by_id": 19,
      		"first_name": "John",
      		"date": "31-Apr-2020",
      		"rating": 5,
      		"comment": "Jane slept all the way to destination."
      	}]
      }

^Top^ ^accounts^

rides

^Top^ ^rides^

Create ride

POST /rides

Creates a ride and returns (in the body of the response) the ID of the ride.

'Location' header with link to /rides/[rid] where [rid] is the newly assigned ID for the ride.

HTTP response code:

  • 201 (Created) if everything is ok.
  • 400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.

Resource URL

/rides

Parameters

aid (required): account ID of the driver who creates the ride.

location_info: Information about departure and arrival points.

  • from_city (required): the name of the starting point (city)
  • from_zip (optional): the zip code where the departure point is located.
  • to_city (required): the arrival point (city)
  • to_zip (optional): the zip code where the arrival point is located.

date_time: Departure date and time information.

  • date (required): departure date in DD-MMM-YYYY format.
  • time (required): departure time in HH:MM format.

car_info: Detail about the car used for the ride.

  • make (required): car make.
  • model (required): car model.
  • color (required): car color.
  • plate_state (required): the state that issued the license plate in the two-letter format used by USPS, e.g. IL for Illinois, TX for Texas, etc.
  • plate_serial (required): the licence plate "number".

max_passengers (required): maximum number of passengers that can share the ride; must be a positive integer.

amount_per_passenger (required): dollar amount per rider; must be a non-negative number.

conditions (required): a potentially empty string.

Example Request

      POST http://localhost:8080/sar/rides

Here is data being POST-ed 

      {
      	"aid": 19,
      	"location_info": {
      		"from_city": "Barrington",
      		"from_zip": "60010",
      		"to_city": "Milwaukee",
      		"to_zip": "53202"
      	},
      	"date_time": {
      		"date": "14-Apr-2020",
      		"time": "09:00"
      	},
      	"car_info": {
      		"make": "Audi",
      		"model": "A4",
      		"color": "Gray",
      		"plate_state": "IL",
      		"plate_serial": "COVID19"
      	},
        "max_passengers": 2,
        "amount_per_passenger": 15.00,
        "conditions": "No more than one carry on per passenger. No pets."
      }

Example Response

      {
        "rid": 123
      }

Example Response when Something Went Wrong

Let's assume that the following data is being POST-ed 

      {
      	"aid": 19,
      	"location_info": {
      		"from_city": "Barrington",
      		"from_zip": "60010",
      		"to_city": "Milwaukee",
      		"to_zip": "53202"
      	},
      	"date_time": {
      		"date": "31-Apr-2020",
      		"time": "09:00"
      	},
      	"car_info": {
      		"make": "Audi",
      		"model": "A4",
      		"color": "Gray",
      		"plate_state": "IL",
      		"plate_serial": "COVID19"
      	},
      	"max_passengers": 2,
      	"amount_per_passenger": 15.00,
      	"conditions": "No more than one carry-on per passenger. No pets."
      }

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": "Invalid date",
        "status": 400,
        "instance": "/rides"
      }

^Top^ ^rides^

Update ride

PUT /rides/[rid]

Updates the ride identified by [rid].

HTTP response codes:

  • 204 (No content) if everything is ok.
  • 400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
  • 404 (Not found) the ride identified by [rid] doesn't exist.

Resource URL

/rides/[rid]

Parameters

aid (required): account ID of the driver who creates the ride. This must match the account ID that created the ride.

location_info: Information about departure and arrival points.

  • from_city (required): the name of the starting point (city)
  • from_zip (optional): the zip code where the departure point is located.
  • to_city (required): the arrival point (city)
  • to_zip (optional): the zip code where the arrival point is located.

date_time: Departure date and time information.

  • date (required): departure date in DD-MMM-YYYY format.
  • time (required): departure time in HH:MM format.

car_info: Detail about the car used for the ride.

  • make (required): car make.
  • model (required): car model.
  • color (required): car color.
  • plate_state (required): the state that issued the license plate in the two-letter format used by USPS, e.g. IL for Illinois, TX for Texas, etc.
  • plate_serial (required): the licence plate "number".

Example Request

      PUT http://localhost:8080/sar/rides/123

Here is the data being PUT 

      {
      	"aid": 19,
      	"location_info": {
      		"from_city": "Barrington",
      		"from_zip": "60010",
      		"to_city": "Milwaukee",
      		"to_zip": "53202"
      	},
      	"date_time": {
      		"date": "14-Apr-2020",
      		"time": "09:30"
      	},
      	"car_info": {
      		"make": "Audi",
      		"model": "A4",
      		"color": "Gray",
      		"plate_state": "IL",
      		"plate_serial": "COVID19"
      	},
      	"max_passengers": 2,
      	"amount_per_passenger": 15.00,
      	"conditions": "No more than one carry-on per passenger. No pets."
      }

Example Successful Response

The body of the response is empty.

Example Response when Something Went Wrong

Let's assume that the following data is being PUT 

      {
      	"aid": 23,
      	"location_info": {
      		"from_city": "Barrington",
      		"from_zip": "60010",
      		"to_city": "Milwaukee",
      		"to_zip": "53202"
      	},
      	"date_time": {
      		"date": "14-Apr-2020",
      		"time": "09:00"
      	},
      	"car_info": {
      		"make": "Audi",
      		"model": "A4",
      		"color": "Gray",
      		"plate_state": "IL",
      		"plate_serial": "COVID19"
      	},
      	"max_passengers": 2,
      	"amount_per_passenger": 15.00,
      	"conditions": "No more than one carry-on per passenger. No pets."
      }

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": "Only the creator of the ride may change it",
        "status": 400,
        "instance": "/rides/123"
      }

^Top^ ^rides^

Delete ride

DELETE /rides/[rid]

Deletes the ride identified by [rid].

HTTP response codes:

  • 204 (No content) if the entity has been removed and there is no additional information in the body of the response.
  • 404 (Not found) if the ride identified by [rid] doesn't exist.

Resource URL

/rides/[rid]

Parameters

None

Example Request

      DELETE http://localhost:8080/sar/rides/123

Example Successful Response

The body of the response is empty.

^Top^ ^rides^

View all rides

GET /rides

Returns a JSON array with all rides.

HTTP response codes:

  • 200 (OK).

Resource URL

/rides

Parameters

None

Example Request

      GET http://localhost:8080/sar/rides

Example Successful Response

      [{
      		"rid": 123,
      		"location_info": {
      			"from_city": "Barrington",
      			"from_zip": "60010",
      			"to_city": "Milwaukee",
      			"to_zip": "53202"
      		},
      		"date_time": {
      			"date": "14-Apr-2020",
      			"time": "09:00"
      		}
      	},
      	{
      		"rid": 127,
      		"location_info": {
      			"from_city": "Chicago",
      			"from_zip": "60616",
      			"to_city": "Rockford",
      			"to_zip": ""
      		},
      		"date_time": {
      			"date": "30-Apr-2020",
      			"time": "15:00"
      		}
      	},
      	{
      		"rid": 131,
      		"location_info": {
      			"from_city": "Chicago",
      			"from_zip": "60616",
      			"to_city": "Grand Rapids",
      			"to_zip": "49503"
      		},
      		"date_time": {
      			"date": "14-Apr-2020",
      			"time": "07:00"
      		}
      	}
      ]

^Top^ ^rides^

View ride detail

GET /rides/[rid]

Get detailed information about the ride identified by [rid].

HTTP response codes:

  • 200 (OK).
  • 404 (Not found) if the ride identified by [rid] doesn't exist.

Resource URL

/rides/[rid]

Parameters

None

Example Request

      GET http://localhost:8080/sar/rides/123

Example Successful Response

      {
      	"rid": 123,
      	"location_info": {
      		"from_city": "Barrington",
      		"from_zip": "60010",
      		"to_city": "Milwaukee",
      		"to_zip": "53202"
      	},
      	"date_time": {
      		"date": "31-Apr-2020",
      		"time": "09:00"
      	},
      	"car_info": {
      		"make": "Audi",
      		"model": "A4",
      		"color": "Gray",
      		"plate_state": "IL",
      		"plate_serial": "COVID19"
      	},
      	"driver": "John",
      	"driver_picture": "http://example.com/images/john-smith.jpeg",
      	"rides": 3,
      	"ratings": 2,
      	"average_rating": 4.5,
      	"comments_about_driver": [{
      			"rid": 47,
      			"date": "13-Apr-2020",
      			"rating": 5,
      			"comment": "Great car, smooth drive, very good conversation."
      		},
      		{
      			"rid": 43,
      			"date": "1-Apr-2020",
      			"rating": 4,
      			"comment": "John drives too fast, I was scared out of my mind."
      		}
      	]
      }

^Top^ ^rides^

Search rides

GET /rides?from=fromkey&to=tokey&date=departure_date

Returns an array of summary ride information for the rides that match the search criteria.

HTTP response codes:

  • 200 (OK).

Resource URL

/rides

Parameters

  • from (required): the origin of a ride. Any ride that has a departure point that that matches "fromkey" (the value of "from") is a candidate to be included in the result set. The search is case insensitive. If "fromkey" is empty, then match everything.
  • to (required): the destination of a ride. Any ride that has an origin that that matches "fromkey" (the value of "from") AND a destination that matches the value of "tokey" will be included in the result set. The search is case insensitive. If "tokey" is empty, then match everything.
  • date (required): find all the rides that have this departure date. Date format: DD-MMM-YYYY. If "departure_date" is empty, then match everything, past, present, and future dates.

    • Example Request

          GET http://localhost:8080/sar/rides?from=Chicago&to=&date=30-apr-2020

    Example Response

          [{
      	"rid": 127,
      	"location_info": {
      		"from_city": "Chicago",
      		"from_zip": "60616",
      		"to_city": "Rockford",
      		"to_zip": ""
      	},
      	"date_time": {
      		"date": "30-Apr-2020",
      		"time": "15:00"
      	}
      }]

    ^Top^ ^rides^

    Request to join ride

    POST /rides/[rid]/join_requests

    Creates a join ride request and returns (in the body of the response) the ID of the request.

    'Location' header with link to /rides/[rid]/join_requests/[jid] where [jid] is the newly assigned ID for the join request.

    HTTP response code:

    • 201 (Created) if everything is ok.
    • 400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.

    Resource URL

    /rides/[rid]/join_requests

    Parameters

    aid (required): account ID of the account that's requesting to join the ride. NOTE: normally the ID of the account making the request would be inferred from the session that was established after the user was authenticated. It is included in most API end points for testing simplicity.

    passengers (required): number of passengers in the party.

    ride_confirmed: initial value is null; will be changed to true after the driver of the ride confirms the passenger(s) for the ride. Alternately it could be set to false if the rider doesn't want to take the passenger(s) on the ride.

    pickup_confirmed: initial value is null; will be changed to true after the passenger who requested to join the ride confirms the pick-up.

    Example Request

          POST http://localhost:8080/sar/rides/123/join_requests

    Here is data being POST-ed 

          {
      	"aid": 67,
      	"passengers": 2,
        "ride_confirmed": null,
        "pickup_confirmed": null
      }

    Example Response

          {
        "jid": "523"
      }

    Example Response when Something Went Wrong

    Let's assume that the following data is being POST-ed 

          {
      	"aid": 67,
      	"passengers": 2,
        "ride_confirmed": true,
        "pickup_confirmed": null
      }

    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": "Invalid value for ride_confirmed",
        "status": 400,
        "instance": "/rides/123/join_requests"
      }

    ^Top^ ^rides^

    Confirm / deny a join ride request

    PATCH /rides/[rid]/join_requests/[jid]

    Updates ride_confirmed in a join ride request. The request must be made by the account that created the ride.

    HTTP response code:

    • 200 (OK) if everything is ok.
    • 400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.

    Resource URL

    /rides/[rid]/join_requests/[jid]

    Parameters

    ride_confirmed: the only valid values are true, if the driver confirms the passenger on the ride, or false if the driver denies the request to join the ride.

    Example Request

          PATCH http://localhost:8080/sar/rides/123/join_requests/523

    Here is data being PATCH-ed 

          {
      	"aid": 19,
        "ride_confirmed": true
      }

    Example Response

    The body of the reponse is empty.

    Example Response when Something Went Wrong

    Let's assume that the following data is being POST-ed 

          {
      	"aid": 19,
        "ride_confirmed": null,
      }

    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": "Invalid value for ride_confirmed",
        "status": 400,
        "instance": "/rides/123/join_requests/523"
      }

    Another Example Response when Something Went Wrong

    Let's assume that the following data is being POST-ed 

          {
      	"aid": 20,
        "ride_confirmed": true,
      }

    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": "This account (20) didn't create the ride (123)",
        "status": 400,
        "instance": "/rides/123/join_requests/523"
      }

    ^Top^ ^rides^

    Confirm passenger pickup

    PATCH /rides/[rid]/join_requests/[jid]

    Updates pickup_confirmed in a join ride request. The request must be made by the account that created the join ride request for this particular ride.

    HTTP response code:

    • 200 (OK) if everything is ok.
    • 400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.

    Resource URL

    /rides/[rid]/join_requests/[jid]

    Parameters

    pickup_confirmed: the only valid value is true, if the passenger confirms the pickup.

    Example Request

          PATCH http://localhost:8080/sar/rides/123/join_requests/523

    Here is data being PATCH-ed 

          {
      	"aid": 67,
        "pickup_confirmed": true
      }

    Example Response

    The body of the reponse is empty.

    Example Response when Something Went Wrong

    Let's assume that the following data is being POST-ed 

          {
      	"aid": 67,
        "ride_confirmed": false,
      }

    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": "Invalid value for pickup_confirmed",
        "status": 400,
        "instance": "/rides/123/join_requests/523"
      }

    Another Example Response when Something Went Wrong

    Let's assume that the following data is being POST-ed 

          {
      	"aid": 70,
        "ride_confirmed": true,
      }

    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": "This account (70) has not requested to join this ride (123)",
        "status": 400,
        "instance": "/rides/123/join_requests/523"
      }

    ^Top^ ^rides^

    Add message to ride

    POST /rides/[rid]/messages

    Adds a message to the ride identified by [rid] and returns (in the body of the response) the ID of the message.

    'Location' header with link to /rides/[rid]/messages/[mid].

    HTTP response code:

    • 201 (Created) if everything is ok.
    • 400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
    • 404 (Not found) if the ride identified by [rid] doesn't exist.

    Resource URL

    /rides/[rid]/messages

    Parameters

    aid (required): account ID of the party, driver or rider, that sends the message.

    msg (required): the body of the message being sent.

    Example Request

          POST http://localhost:8080/sar/rides/123/messages

    Here is data being POST-ed 

          {
      	"aid": 67,
      	"msg": "One passenger; could you pick me up at the Starbucks in Barrington at Main and Hough?"
      }

    Example Response

          {
        "mid": "211"
      }

    Example Response when Something Went Wrong

    Let's assume that the following data is being POST-ed 

          {
      	"aid": 67,
      	"msg": "One passenger; could you pick me up at the Starbucks in Barrington at Main and Hough?"
      }

    If the accunt with aid=67 is not active, then the response body may look like this: 

          {
        "type": "http://cs.iit.edu/~virgil/cs445/project/api/problems/data-validation",
        "title": "Your request data didn't pass validation",
        "detail": "Account is not active",
        "status": 400,
        "instance": "/rides/123/messages"
      }

    ^Top^ ^rides^

    View all ride messages

    GET /rides/[rid]/messages

    Get an array of messages associated with the ride identified by [rid].

    HTTP response codes:

    • 200 (OK).
    • 404 (Not found) if the ride identified by [rid] doesn't exist.

    Resource URL

    /rides/[rid]/messages

    Parameters

    None

    Example Request

          GET http://localhost:8080/sar/rides/123/messages

    Example Response

          [{
      		"mid": 211,
      		"sent_by_aid": 67,
      		"date": "12-Apr-2020, 17:23:15",
      		"body": "One passenger; could you pick me up at the Starbucks in Barrington at Main and Hough?"
      	},
      	{
      		"mid": 229,
      		"sent_by_aid": 19,
      		"date": "12-Apr-2020, 17:30:19",
      		"body": "Ok, will do, see you on Tuesday morning"
      	}
      ]

    ^Top^ ^rides^

    reports

    ^Top^ ^reports^

    View all reports

    GET /reports

    Returns an array of report IDs with their corresponding names.

    HTTP response code: 200 (OK).

    Resource URL

    /reports

    Parameters

    None.

    Example Request

    
      GET http://localhost:8080/sar/reports

    Example Response

          [{
          "pid": 907,
          "name": "Rides posted between two dates"
        }, {
          "pid": 911,
          "name": "Rides taken between two dates"
        }
      ]

    ^Top^ ^reports^

    Get report

    GET /reports/[pid]{?start_date=DD-MMM-YYYY&end_date=DD-MMM-YYYY}

    Returns the report identified by [pid]. If no dates are provided, then include all rides you have in the system. If a start_date is provided and no end_date, then include all rides with a departure date on the start_date and after. If only the end_date is specified, then include all rides with a departure date prior to and on the end_date. Finally, if both the start_date and end_date are provided, then only include rides in that range (including rides on the start and end dates).

    HTTP response codes:

    • 200 (OK).
    • 404 (Not Found) if [pid] doesn't exist.

    Resource URL

    /reports/[pid]

    Parameters

    • 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/sar/reports/907

    Example Response

    This example response is based on the data shown in the View all rides example. 

          {
      	"pid": 907,
      	"name": "Rides posted between two dates",
      	"start_date": "",
      	"end_date": "",
      	"rides": 3,
      	"detail": [{
      			"from_zip": "60010",
      			"to_zip": "53202",
      			"count": 1
      		},
      		{
      			"from_zip": "60616",
      			"to_zip": "",
      			"count": 1
      		},
      		{
      			"from_zip": "60616",
      			"to_zip": "49503",
      			"count": 1
      		}
      	]
      }

    Another Example Request

          GET http://localhost:8080/sar/reports/911?start_date=14-Apr-2020&end_date=14-Apr-2020

    Example Response

          {
      	"pid": 911,
      	"name": "Rides taken between two dates",
      	"start_date": "14-Apr-2020",
      	"end_date": "14-Apr-2020",
      	"rides": 2,
      	"detail": [{
      			"from_zip": "60010",
      			"to_zip": "53202",
      			"count": 1
      		},
      		{
      			"from_zip": "60616",
      			"to_zip": "49503",
      			"count": 1
      		}
      	]
      }

    ^Top^ ^reports^

    search
    • (*) Search ( GET /search?key=keyword{&start_date=DD-MMM-YYYY&end_date=DD-MMM-YYYY} )

    ^Top^ ^search^

    (*) Search

    GET /search?key=keyword{&start_date=DD-MMM-YYYY&end_date=DD-MMM-YYYY}

    NOTE: there is no use case in the requirements that requires this functionality, therefore no implementation required.

    ^Top^ ^search^

    Known limitations

    This section lists all known discrepancies between the requirements and the API.

    • An inactive account can search for rides. That's because search is a GET request and the account ID of the requester is not part of the URI. In real life the ID of the user is part of the session that gets established after the user is authenticated, so the requirements could actually be enforced.
    • Join ride requests are created using POST /rides/<[aid]>/join_requests. However, there is no end point for accessing (view, update, delete) join ride requests. So, what should the HTTP status be when such a request is sent to the server (e.g. GET /rides/<[aid]>/join_requests/<[jid]>)? The only two that come to mind are 405 (Method Not Allowed) and 501 (Not Implemented), however neither is really a good fit. Here's why:
      • The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response MUST include an Allow header containing a list of valid methods for the requested resource. So, what exaclty are we going to list in the Allow header? The "method" here really refers to the VERBs that represent REST actions, e.g. GET, PUT, POST, PATCH, DELETE, etc.
      • The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource. NOTE the "any resource" part; clearly the server knows how to fulfill a GET for most resources, but we choose not to do it for *some* resources.
    Last update: March 27, 2020 Virgil Bistriceanu cs445 Computer Science