API Documentation

• Authentication
• Settings
• Locations
• Availability
• Rides

Authentication

TODO

Settings

TODO

Locations

GET /locations

**Description:**

Return all locations saved by the user.

Response Example:

[
  {
    "id": 1,
    "street_address": "123 Pine St.",
    "city": "Durham",
    "state": "NC",
    "zip": "27609"
  },
  {
    "id": 2,
    "street_address": "123 Oak St.",
    "city": "Durham",
    "state": "NC",
    "zip": "27609"
  },
]

POST /locations

Description:

Save a location for future use.

Request Body:

{
  "street_address": "123 Oak St.",
  "city": "Durham",
  "state": "NC",
  "zip": "27609"
}

Response:

{
  "id": 3,
  "street_address": "123 Oak St.",
  "city": "Durham",
  "state": "NC",
  "zip": "27609"
}

DELETE /locations/:id

Description:

Deletes an address from the list of saved addresses.

Response:

{ success: true }

Availability

GET /availabilities

**Description:**

Returns an array with all the scheduled available time slots within the given range.

Params:

• start: timestamp where range begins
• end: timestamp where range ends

Response Example:

[
  {
    "id": 1,
    "start": "2019-02-07 18:00",
    "end": "2019-02-07 20:00",
    "recurring": true,
    "location": {
      "street_address": "123 Pine St.",
      "city": "Durham",
      "state": "NC",
      "zip": "27609"
    }
  },
  {
    "id": 2,
    "start": "2019-02-08 18:00",
    "end": "2019-02-08 20:00",
    "recurring": false,
    "location": {
      "street_address": "123 Pine St.",
      "city": "Durham",
      "state": "NC",
      "zip": "27609"
    }
  },
  {
    "id": 1,
    "start": "2019-02-14 18:00",
    "end": "2019-02-14 20:00",
    "recurring": true,
    "location": {
      "street_address": "123 Pine St.",
      "city": "Durham",
      "state": "NC",
      "zip": "27609"
    }
  },
]

POST /availabilities

Description:

Save a new availability

Request Body:

{
  "start_date": "2019-02-14 18:00",
  "end_date": "2019-02-14 20:00",
  "start_time": "2019-02-14 18:00",
  "end_time": "2019-02-14 20:00",
  "recurring": true,
  "location_id": 1
}

Response:

{
  "id": 6,
  "start": "2019-02-14 18:00",
  "end": "2019-02-14 20:00",
  "recurring": true,
  "location": {
    "street_address": "123 Pine St.",
    "city": "Durham",
    "state": "NC",
    "zip": "27609"
  }
}

PUT /availabilities/:id

Description:

Update an existing availability

Request Body:

{
  "id": 6,
  "start": "2019-02-14 18:00",
  "end": "2019-02-14 20:00",
  "recurring": true,
  "location": {
    "street_address": "123 Pine St.",
    "city": "Durham",
    "state": "NC",
    "zip": "27609"
  }
}

Response:

{
  "id": 6,
  "start": "2019-02-14 18:00",
  "end": "2019-02-14 20:00",
  "recurring": true,
  "location": {
    "street_address": "123 Pine St.",
    "city": "Durham",
    "state": "NC",
    "zip": "27609"
  }
}

DELETE /locations/:id

Description:

Removes an availability

Response:

{ success: true }

Rides

GET /rides

**Description:**

Returns an array with all the rides within a given range

Params:

• start: optional timestamp where range begins
• end: optional timestamp where range ends
• states: optional list of states the rides are in

Possible States:

• pending: request has been made but has not been approved by the organization
• approved: request has been approved and drivers alerted about ride
• scheduled: request has been matched with a driver and scheduled
• picking-up: driver has started driving to pick up rider (discuss)
• dropping-off: driver has picked up rider and is driving to final destination (discuss)
• completed: driver has dropped of rider at final destination
• canceled: driver or rider has canceled the ride

Response Example: GET /api/v1/rides?start=2019-01-01&end=2019-02-01&states=approved,scheduled

[
  {
    "id": 1,
    "pickupTime": "2019-02-07 18:00",
    "riderName": "John Smith",
    "riderPhone": "919-123-4567",
    "state": "scheduled",
    "pickupLocation": {
      "street_address": "123 Pine St.",
      "city": "Durham",
      "state": "NC",
      "zip": "27609"
    },
    "dropoffLocation": {
      "street_address": "124 Pine St.",
      "city": "Durham",
      "state": "NC",
      "zip": "27609"
    }
  },
  {
    "id": 2,
    "pickupTime": "2019-02-07 18:00",
    "riderName": "Amy Smith",
    "riderPhone": "919-123-4568",
    "state": "approved",
    "pickupLocation": {
      "street_address": "124 Pine St.",
      "city": "Durham",
      "state": "NC",
      "zip": "27609"
    },
    "dropoffLocation": {
      "street_address": "123 Pine St.",
      "city": "Durham",
      "state": "NC",
      "zip": "27609"
    }
  },
]

POST /rides/:id/accept

Description:

Driver accepts the ride

Request Body:

{
}

Response:

{
  "id": 2,
  "pickupTime": "2019-02-07 18:00",
  "riderName": "Amy Smith",
  "riderPhone": "919-123-4568",
  "state": "scheduled",
  "pickupLocation": {
    "street_address": "124 Pine St.",
    "city": "Durham",
    "state": "NC",
    "zip": "27609"
  },
  "dropoffLocation": {
    "street_address": "123 Pine St.",
    "city": "Durham",
    "state": "NC",
    "zip": "27609"
  }
}

POST /rides/:id/complete

Description:

Driver complete the ride

Request Body: In the future we might want to get feedback from the driver here.

{
}

Response:

{
  "id": 2,
  "pickupTime": "2019-02-07 18:00",
  "riderName": "Amy Smith",
  "riderPhone": "919-123-4568",
  "state": "complete",
  "pickupLocation": {
    "street_address": "124 Pine St.",
    "city": "Durham",
    "state": "NC",
    "zip": "27609"
  },
  "dropoffLocation": {
    "street_address": "123 Pine St.",
    "city": "Durham",
    "state": "NC",
    "zip": "27609"
  }
}

POST /rides/:id/cancel

Description:

Driver cancels the ride

Request Body:

{
  "message": "my car broke down"
}

Response:

{
  "id": 2,
  "pickupTime": "2019-02-07 18:00",
  "riderName": "Amy Smith",
  "riderPhone": "919-123-4568",
  "state": "cancele",
  "pickupLocation": {
    "street_address": "124 Pine St.",
    "city": "Durham",
    "state": "NC",
    "zip": "27609"
  },
  "dropoffLocation": {
    "street_address": "123 Pine St.",
    "city": "Durham",
    "state": "NC",
    "zip": "27609"
  }
}