NAV
shell

Introduction

The Hacksmiths Food Drivr API is fairly easy to use. When in doubt, follow REST principles.

Most requests require specific headers. Make sure to include the Content-Type header and the Authorization header for any request. The only exception to this is when you are creating a User or a Session, in which case you will not yet have an Auth token.

REST & HTTP Methods

With this API, there are 4 main HTTP methods you will use. * GET Get will get you data, either in the form of an array or a singular JSON object.

Headers

To the right, you will see an example of your typical headers.

  "Content-Type: application/json"  
  "Authorization: your_authorization_token"

Create a User

To create / register a user, you will create a User object containing the Name, Username, Password and Password Confirmation. Pass the user object to the users endpoint via the POST method and you will get back a User object with an auth_token.

Make sure to pass in a role_id. If the user is a driver, pass in 1, otherwise if they are a donor pass in 0. We will put a mechanism in place for approving drivers, so expect that you will not get an auth token back if the user is a driver until they are approved.

The object that you submit when creating a User will look like this

{
    "user" : {
        "name": "Frank Robert",
        "email": "frank@helloworld.com",
        "password": "helloworld1234",
        "password_confirmation" :"helloworld1234",
        "role_id": 0
    }
}

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/users

Method:POST

HTTP Request

URL Params

Parameter Type Description
name String
email String
password String
password_confirmation String

Success Response

Sample user object

{
  "user": {
    "id": 7,
    "phone": null,
    "name": "Ryan Collins",
    "email": "frank@helloworld.com",
    "avatar": null,
    "role_id": 0,
    "created_at": "2016-04-14T22:28:46.523Z",
    "updated_at": "2016-04-14T22:28:46.523Z",
    "auth_token": "somerandomstringhere",
    "setting": {
      "notifications": true,
      "active": true,
      "created_at": "2016-04-15T16:11:41.186Z",
      "updated_at": "2016-04-15T16:11:41.186Z"
    },
    "organization": {
      TBD
    },
    "permissions": {
      TBD
    }
  }
}

Error Response

The API expects for an auth token to be included in all API requests to the server.

Users

The users resource is setup primarily to provide a mechanism for interacting with a User’s profile. Most actions taken by a User, either a Donor or A Driver are namespaced so that a Donor and Driver have separate actions they can fulfill via the endpoints.

Get a Single User

Getting a user is as simple as making a GET request with an Auth token in the header. The user resource is protected to only allow the authenticated user to access their own user data. 

curl -v \
  -H "Content-Type: application/json" \
  -H "Authorization: auth_token" \
  "https://wastenotfoodtaxi.herokuapp.com/api/v1/user/3"

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/users/:auth_token)

Method:GET

HTTP Request

Parameter Type Description
auth_token Int The user’s auth_token

Success Response

Error Response

Update a User

To update a user, simply create a PATCH request to the user endpoint. You will pass in a JSON object containing any of the parameters you need to authenticate.

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/users/:auth_token

Method:PATCH

HTTP Request

Pass an object that contains all of the User data you want to update. Must match the User JSON model.

Sample user object

{
  "user": {
    "id": 7,
    "phone": "5555555555",
    "name": "Ryan Collins",
    "email": "frank@helloworld.com",
    "avatar": "http://helloworld.com/helloworld.png",
    "role_id": 0,
    "setting": {
      "notifications": true,
      "active": true,
      "created_at": "2016-04-15T16:11:41.186Z",
      "updated_at": "2016-04-15T16:11:41.186Z"
    },
    "organization": {
      TBD
    },
    "permissions": {
      TBD
    }
  }
}

Success Response

Sessions

Create a Session

To signin a user, you will want to create a session. This will take a username and a password and will return an auth token that can be used to authenticate protected resources.

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/sessions

Method:POST

HTTP Request

You will pass the email address and password as a session JSON object.

You will send a JSON object to create the session as shown below.

{
    "session" : {
        "email": "frank@helloworld.com",
        "password": "helloworld1234"
    }
}

HTTP Response

Success: A User object, as shown above under Registering a User. Error: 4XX

curl -v \
  -H "Content-Type: application/json" \
  -H "Authorization: auth_token" \
  "https://wastenotfoodtaxi.herokuapp.com/api/v1/sessions"

Destroy a Session

To signout a user, you will need to submit a DELETE request to the sessions endpoint. Pass in the user’s auth token as a URL parameter.

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/sessions/:auth_token

Method:DELETE

HTTP Request

HTTP Response

Success: 204, No Content Error: 4XX

curl -v \
  -H "Content-Type: application/json" \
  -H "Authorization: auth_token" \
  "https://wastenotfoodtaxi.herokuapp.com/api/v1/sessions/KoPrTKYYMzqmrEJQsnAb"

Donations

You can get a list of donations, get a single donation, create a single donation and update a donation.

Example enum in Ryan (a new programming language) for DonationStatus enum DonationStatus: Int { PendingAction = 0 Accepted = 1 Completed = 2 Cancelled = 3 }

Get All Donations

To get a list of donations, submit a GET request to the donations endpoint. Make sure to include your auth token, as described above. You will get an array of donations (See below).

curl -v \
  -H "Content-Type: application/json" \
  -H "Authorization: auth_token" \
  "https://wastenotfoodtaxi.herokuapp.com/api/v1/donations"

An example of the data returned from the endpoint is shown below

{
  "donations": [
    {
       "id": 7,
       "description": "Legacy description field before items were added. Ignore.",
       "note": "Make sure to pull around back",
       "created_at": "2016-05-07T23:45:50.287Z",
       "updated_at": "2016-05-07T23:45:50.287Z",
       "status_id": 1,
       "status": {
         "id": 1,
         "description": "Accepted"
       },
       "participants": {
         "donor": {
           "id": 1,
           "phone": "+1 123 456 789",
           "name": "Donor User",
           "email": "donor@hacksmiths.com",
           "avatar": null
         },
         "driver": {
           "id": 74,
           "phone": "1-775-894-8780",
           "name": "Gennaro Rau",
           "email": "nya@beattysmitham.name",
           "avatar": null
         }
       },
       "pickup": {
         "estimated": null,
         "actual": null,
         "latitude": "0.0",
         "longitude": "0.0",
         "street_address": null,
         "street_address_two": null,
         "city": null,
         "state": null,
         "zip": null,
         "status": {
           "id": 0,
           "description": "Pending"
         },
         "status_id": 0
       },
       "dropoff": {
         "estimated": "2014-01-23T00:00:00.000Z",
         "actual": "2016-03-01T00:00:00.000Z",
         "latitude": "40.8377346033",
         "longitude": "-81.611008",
         "street_address": "13831 Youth Street Northwest",
         "street_address_two": "Apt. 558",
         "city": "North Lawrence",
         "state": "Ohio",
         "zip": "44666",
         "status": {
           "id": 0,
           "description": "Pending"
         },
         "status_id": 0
       },
       "recipient": {
         "id": 5,
         "name": "Christiansen, Crona and West",
         "street_address": "80324 Marcellus Centers",
         "street_address_two": "Suite 947",
         "city": "Weissnatshire",
         "phone": 1,
         "created_at": "2016-05-07T23:45:39.842Z",
         "updated_at": "2016-05-07T23:45:39.842Z",
         "state": "Florida",
         "zip": "05582",
         "country_code": "US",
         "latitude": "0.0",
         "longitude": "0.0"
       },
       "items": [
         {
           "description": "Ostrich",
           "unit": "t",
           "quantity": 4
         },
         {
           "description": "Veal",
           "unit": "gr",
           "quantity": 18
         },
         {
           "description": "Venison",
           "unit": "cwt",
           "quantity": 16
         },
         {
           "description": "Chicken",
           "unit": "gr",
           "quantity": 12
         },
         {
           "description": "Bone soup from allowable meats",
           "unit": "gr",
           "quantity": 11
         },
         {
           "description": "Liver",
           "unit": "gr",
           "quantity": 7
         }
       ],
       "images": []
     },
     {
       "id": 16,
       "description": "Banh mi butcher mlkshk cardigan viral hoodie tofu.",
       "created_at": "2016-05-07T23:45:50.464Z",
       "updated_at": "2016-05-07T23:45:50.464Z",
       "status_id": 1,
       "status": {
         "id": 1,
         "description": "Accepted"
       },
       "participants": {
         "donor": {
           "id": 1,
           "phone": "+1 123 456 789",
           "name": "Donor User",
           "email": "donor@hacksmiths.com",
           "avatar": null
         },
         "driver": {
           "id": 42,
           "phone": "(267)163-4915 x7030",
           "name": "Braulio Jacobi",
           "email": "pearlie.kunde@crooksbuckridge.ca",
           "avatar": null
         }
       },
       "pickup": {
         "estimated": null,
         "actual": null,
         "latitude": "0.0",
         "longitude": "0.0",
         "street_address": null,
         "street_address_two": null,
         "city": null,
         "state": null,
         "zip": null,
         "status": {
           "id": 0,
           "description": "Pending"
         },
         "status_id": 0
       },
       "dropoff": {
         "estimated": "2012-11-23T00:00:00.000Z",
         "actual": "2015-03-04T00:00:00.000Z",
         "latitude": "33.4280828891",
         "longitude": "-87.888795",
         "street_address": "Elmore Road",
         "street_address_two": "Apt. 261",
         "city": "Gordo",
         "state": "Alabama",
         "zip": "35466",
         "status": {
           "id": 0,
           "description": "Pending"
         },
         "status_id": 0
       },
       "recipient": {
         "id": 16,
         "name": "Lowe-Kihn",
         "street_address": "11573 New York 22",
         "street_address_two": "Apt. 524",
         "city": "Comstock",
         "phone": 950,
         "created_at": "2016-05-07T23:45:46.477Z",
         "updated_at": "2016-05-07T23:45:46.477Z",
         "state": "New York",
         "zip": "12821",
         "country_code": "US",
         "latitude": "43.46012",
         "longitude": "-73.4121277"
       },
       "items": [
         {
           "description": "Turtle",
           "unit": "t",
           "quantity": 1
         },
         {
           "description": "Quail",
           "unit": "gr",
           "quantity": 10
         },
         {
           "description": "Pheasant",
           "unit": "lb",
           "quantity": 12
         },
         {
           "description": "Beef liver",
           "unit": "t",
           "quantity": 20
         },
         {
           "description": "Chicken Liver",
           "unit": "t",
           "quantity": 2
         },
         {
           "description": "Ostrich",
           "unit": "lb",
           "quantity": 7
         }
       ],
       "images": []
     }
  ]
}

HTTP Request

GET https://wastenotfoodtaxi.herokuapp.com/api/v1/donations

Method

GET

HTTP Response

Success: 2XX and a Donations array as shown above Error: 4XX

Query Parameters

Parameter Default Description
status 0 Will return the most recent pending donations
embedded true If included, user relationships are automatically included in the JSON object. i.e. return donor object in JSON vs. donor_id.

Update a Donation

To update a donation, you will submit a PATCH to the donations endpoint. Submit any parameters that will need to be updated, following the schema above for the donation JSON object.

An example request shell curl -v \ -H "Content-Type: application/json" \ -H "Authorization: auth_token" \ "https://wastenotfoodtaxi.herokuapp.com/api/v1/donations/:id"

HTTP Request

GET https://wastenotfoodtaxi.herokuapp.com/api/v1/donations/:id

URL Parameters

Parameter Description
ID The ID of the donation to update
Other Donation Params Follow the schema defined above for donations

Get a Specific Donation

curl "https://wastenotfoodtaxi.herokuapp.com/api/v1/donations/:id"
  -H "Authorization: user_token"

The above command returns JSON structured like this:

{
  "donation": {
    "id": 7,
    "note": "Optional note to the driver, should they need more instructions about a donation.",
    "created_at": "2016-05-07T23:45:50.287Z",
    "updated_at": "2016-05-07T23:45:50.287Z",
    "status_id": 1,
    "status": {
      "id": 1,
      "description": "Accepted"
    },
    "participants": {
      "donor": {
        "id": 1,
        "phone": "+1 123 456 789",
        "name": "Donor User",
        "email": "donor@hacksmiths.com",
        "avatar": null
      },
      "driver": {
        "id": 74,
        "phone": "1-775-894-8780",
        "name": "Gennaro Rau",
        "email": "nya@beattysmitham.name",
        "avatar": null
      }
    },
    "pickup": {
      "estimated": null,
      "actual": null,
      "latitude": "0.0",
      "longitude": "0.0",
      "street_address": null,
      "street_address_two": null,
      "city": null,
      "state": null,
      "zip": null,
      "status": {
        "id": 0,
        "description": "Pending"
      },
      "status_id": 0
    },
    "dropoff": {
      "estimated": "2014-01-23T00:00:00.000Z",
      "actual": "2016-03-01T00:00:00.000Z",
      "latitude": "40.8377346033",
      "longitude": "-81.611008",
      "street_address": "13831 Youth Street Northwest",
      "street_address_two": "Apt. 558",
      "city": "North Lawrence",
      "state": "Ohio",
      "zip": "44666",
      "status": {
        "id": 0,
        "description": "Pending"
      },
      "status_id": 0
    },
    "recipient": {
      "id": 5,
      "name": "Christiansen, Crona and West",
      "street_address": "80324 Marcellus Centers",
      "street_address_two": "Suite 947",
      "city": "Weissnatshire",
      "phone": 1,
      "created_at": "2016-05-07T23:45:39.842Z",
      "updated_at": "2016-05-07T23:45:39.842Z",
      "state": "Florida",
      "zip": "05582",
      "country_code": "US",
      "latitude": "0.0",
      "longitude": "0.0"
    },
    "items": [
      {
        "description": "Ostrich",
        "unit": "t",
        "quantity": 4
      },
      {
        "description": "Veal",
        "unit": "gr",
        "quantity": 18
      },
      {
        "description": "Venison",
        "unit": "cwt",
        "quantity": 16
      },
      {
        "description": "Chicken",
        "unit": "gr",
        "quantity": 12
      },
      {
        "description": "Bone soup from allowable meats",
        "unit": "gr",
        "quantity": 11
      },
      {
        "description": "Liver",
        "unit": "gr",
        "quantity": 7
      }
    ],
    "images": []
  }
}

This endpoint retrieves a specific donation.

HTTP Request

GET https://wastenotfoodtaxi.herokuapp.com/api/v1/donations/:id

URL Parameters

Parameter Description
ID The ID of the donation to retrieve

Donors

The biggest functionality needed for Donors is the ability to donate food.

Create a Donation

As a signed in Donor, you can create a Donation

{
    "donation": {
        "description": "Legacy field before itemized descriptions was added",
        "note": "A note to the driver, optional",
        "pickup_location": {
          "latitude": 36.3817670,
          "longitude": -75.8288640
        },
        "items": [
            {
                "description": "sushi",
                "quantity": "34",
                "unit": "boxes"
            },
            {
                "description": "bratwurst",
                "quantity": "25",
                "unit": "cans"
            }
        ]
    }
}

Update a Donation

Drivers

Drivers have a few main actions they can take to initiate a pickup, change the status of a donation and dropoff the food.

When a donation is created, the location where the food will be picked up is set based on the Donor’s default address. If they do not have a default address, you’ll need to submit a location along with the donation to be specific. We do not want Driver’s picking up food at the wrong location, so all of the client’s need a verify your address step. To pickup a donation, a driver will accept the donation. At each step along the way, the driver sends status updates to the server. Actions that can be accomplished by a driver include: accept to pickup the food,

Check Status of A Non-Approved Driver

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/driver/status

Method:GET

HTTP Request

HTTP Response

Success: 2XX + an active field, showing if the driver has yet to be activated Error: 4XX

An example of the JSON received back from a status check json { "active": false }

Driver Donations

Although you can interact with donations through the /donations endpoint, it makes more sense to have them semantically accessible through the driver endpoint. Also, it provides an interface for interacting with donations specific to a driver. For example, you can get a list of all the donations for a specific driver, including Pending donations that have yet to be assigned to a driver. You also have convenience methods for getting a Driver’s donation list based on the status of the donation.

Get All Donations (Pending, Accepted, Completed, Cancelled)

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/driver/donations/all

METHOD: GET

HTTP Request

N/A

HTTP Response

Success: 2XX and an array of Donations, All Pending, and all attached to a Driver

Get all Pending Donations

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/driver/donations/pending

METHOD: GET

HTTP Request

N/A

HTTP Response

Success: 2XX and an array of Donations, All Pending Error: 4XX

Get all Accepted Donations Attached to a Driver

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/driver/donations/accepted

METHOD: GET

HTTP Request

N/A

HTTP Response

Success: 2XX and an array of Donations, All Accepted

Get all Pending Donations and all Donations tied to a Driver

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/driver/donations/all

METHOD: GET

HTTP Request

N/A

HTTP Response

Success: 2XX and an array of Donations, All Completed

Get all Cancelled Donations

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/driver/donations/cancelled

METHOD: GET

HTTP Request

N/A

HTTP Response

Success: 2XX and an array of Donations, All Cancelled

Get a Single Donation by ID

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/driver/donations/:donation_id

METHOD: GET

HTTP Request

N/A

HTTP Response

Success: 2XX and a single Donation Error: 403 if the Donation belongs to another driver.

Update the Status of a Single Donation

To update the status of a donation, send a request to POST

URL

https://wastenotfoodtaxi.herokuapp.com/api/v1/driver/donations/:donation_id/status

METHOD: POST

HTTP Request

Note: The below objects match the three status fields to the status updates a driver will send.

Pending { "status": { "donation_status": 0, "pickup_status": 0, "dropoff_status": 0 } }

Accepted by driver, but not yet picked up json { "status": { "donation_status": 1, "pickup_status": 1, "dropoff_status": 1 } }

Picked up by driver json { "status": { "donation_status": 1, "pickup_status": 2, "dropoff_status": 1 } }

Dropped off by driver json { "status": { "donation_status": 2, "pickup_status": 2, "dropoff_status": 2 } }

Cancelled: Note, a 4 in any status field will set the status of the rest to 4 json { "status": { "donation_status": 4, "pickup_status": 4, "dropoff_status": 4 } }

HTTP Response

Success: 2XX and an array of Donations, All Cancelled

Errors

The Food Drivr API uses the following error codes:

Common error codes

Error Code Meaning
400 Bad Request – Your request cannot be understood
401 Unauthorized – Your token is wrong
403 Forbidden – The data requested is hidden for administrators only
404 Not Found – The specified data could not be found
405 Method Not Allowed – You tried to access data with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The data requested has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too much data! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Error codes in depth, with Rails symbols

Code Meaning Symbol
1xx Informational
100 Continue :continue
101 Switching Protocols :switching_protocols
102 Processing :processing
2xx Success
200 OK :ok
201 Created :created
202 Accepted :accepted
203 Non-Authoritative Information :non_authoritative_information
204 No Content :no_content
205 Reset Content :reset_content
206 Partial Content :partial_content
207 Multi-Status :multi_status
226 IM Used im_used
3xx Redirection
300 Multiple Choices :multiple_choices
301 Moved Permanently :moved_permanently
302 Found :found
303 See Other :see_other
304 Not Modified :not_modified
305 Use Proxy :use_proxy
307 Temporary Redirect :temporary_redirect
4xx Client Error
400 Bad Request :bad_request
401 Unauthorized :unauthorized
402 Payment Required :payment_required
403 Forbidden :forbidden
404 Not Found :not_found
405 Method Not Allowed :method_not_allowed
406 Not Acceptable :not_acceptable
407 Proxy Authentication Required :proxy_authentication_required
408 Request Timeout :request_timeout
409 Conflict :conflict
410 Gone :gone
411 Length Required :length_required
412 Precondition Failed :precondition_failed
413 Request Entity Too Large :request_entity_too_large
414 Request-URI Too Long :request_uri_too_long
415 Unsupported Media Type :unsupported_media_type
416 Requested Range Not Satisfiable :requested_range_not_satisfiable
417 Expectation Failed :expectation_failed
422 Unprocessable Entity :unprocessable_entity
423 Locked :locked
424 Failed Dependency :failed_dependency
426 Upgrade Required :upgrade_required
5xx Server Error
500 Internal Server Error :internal_server_error
501 Not Implemented :not_implemented
502 Bad Gateway :bad_gateway
503 Service Unavailable :service_unavailable
504 Gateway Timeout :gateway_timeout
505 HTTP Version Not Supported :http_version_not_supported
507 Insufficient Storage :insufficient_storage
510 Not Extended :not_extended
shell