Project API

For purposes of this API description, all URLs are relative to the base url of http://localhost:8080/vin

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.

Subscriber

POST /sub

Creates a subscriber account. Returns the id of the account created and an array of errors.

HTTP response codes: 201 (Created), 'Location' header with link to /sub/account/{id} containing new ID.

Resource URL

/sub

Parameters

email (required): subscriber email address; must be unique across accounts.

name (required): subscriber name (first last).

phone (required): subscriber phone number.

address (required): subscriber address.

facebook (optional): facebook name.

twitter (optional): twitter username.

Example Request

	
  POST http://localhost:8080/vin/sub

Here is data being POST-ed 

  
  {
    "email": "jane.doe@example.com",
    "name": "Jane Doe",
    "phone": "123-456-7890",
    "address": {
      "street": "123 Main ST, Apt 2F",
      "city": "Anytown",
      "state": "Anystate",
      "zip": "12345"
    },
    "facebook": "",
    "twitter": ""   
  }

Example Response


  {
    "id": 345,
    "errors": []
  }

Here is another example 


  {
      "id": null,
      "errors": [
          {
              "code": 789,
              "message": "State must be specified"
          },
          {
              "code": 790,
              "message": "invalid email address"
          }
      ]
  }

PUT /sub/{uid}

Updates a subscriber account identified by {uid}. Returns an array of errors.

HTTP response codes: 200 (OK) or 204 (No Content). 404 (Not Found), if {uid} not found or invalid.

Resource URL

/sub/{uid}

Parameters

email (required): subscriber email address; must be unique across accounts.

name (required): subscriber name (first last).

phone (required): subscriber phone number.

address (required): subscriber address.

facebook (optional): facebook name.

twitter (optional): twitter username.

Example Request

	
  PUT http://localhost:8080/vin/sub/345

Here is data being PUT 

  
  {
    "email": "jane.doe@example.com",
    "name": "Jane Doe",
    "phone": "123-456-7890",
    "address": {
      "street": "123 Main ST, STE A",
      "city": "Anytown",
      "state": "Anystate",
      "zip": "12345"
    },
    "facebook": "",
    "twitter": ""   
  }

Example Response


  {
    "errors": []
  }

GET /sub/{uid}

Returns account information for the subscriber identified by {uid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid.

Resource URL

/sub/{uid}

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/sub/345

Example Response


  {
    "email": "jane.doe@example.com",
    "name": "Jane Doe",
    "phone": "123-456-7890",
    "address": {
      "street": "123 Main ST, STE A",
      "city": "Anytown",
      "state": "Anystate",
      "zip": "12345"
    },
    "facebook": "",
    "twitter": ""   
  }

GET /sub/{uid}/search[?q=query_string]

Returns an array of wine IDs, array of note IDs, and shipments IDs that contain the query_string.

HTTP response code: 200 (OK).

Resource URL

/sub/{uid}/search

Parameters

q (optional): query string (aka keyword) used for search, if none specified, then everything matches.

Example Request

	
  GET http://localhost:8080/vin/sub/345/search?q=red

Example Response


  {
      "wines": [
          {
              "id": 123,
              "label_name": "The Mission"
          },
          {
              "id": 124,
              "label_name": "Joseph Phelps Cabernet Sauvignon 2012"
          }
      ],
      "notes": [],
      "shipments": [
          {
              "id": 145,
              "selection_month": "Mar/2015"
          }
      ]
  }

GET /sub/{uid}/shipments

Returns an array of shipments for the subscriber identified by {uid}. For each shipment return the status, e.g. "delivered", "cancelled", "returned".

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid.

Resource URL

/sub/{uid}/shipments

Parameters

None. In a future incarnation of this project, parameters may include a start and end date.

Example Request

	
  GET http://localhost:8080/vin/sub/345/shipments

Example Response


  {
      "shipments": [
          {
              "id": 131,
              "selection_month": "Jan/2015",
              "status": "delivered"
          },
          {
              "id": 139,
              "selection_month": "Feb/2015",
              "status": "cancelled"
          },
          {
              "id": 145,
              "selection_month": "Mar/2015",
              "status": "delivered"
          }
      ]
  }

GET /sub/{uid}/shipments/{sid}

Returns detailed information about the shipment identified by {sid} for subscriber identified by {uid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {sid} not found or invalid.

Resource URL

/sub/{uid}/shipments/{sid}

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/sub/345/shipments/139

Example Response


  {
    "selection_month": "Feb/2015",
    "status": "cancelled",
    "date": "13-Feb-2015",
    "type": "AR",
    "wines": [
        {
            "id": 123,
            "label_name": "The Mission"
        },
        {
            "id": 124,
            "label_name": "Joseph Phelps Cabernet Sauvignon 2012"
        },
        {
            "id": 125,
            "label_name": "Round Pond Estate Rutherford"
        },
        {
            "id": 126,
            "label_name": "Dona Paula Black Label"
        },
        {
            "id": 127,
            "label_name": "Schug Sonoma Coast Pinot Noir"
        },
        {
            "id": 128,
            "label_name": "Caymus Special Selection Cabernet Sauvignon "
        }
    ]
  }

PUT /sub/{uid}/shipments/{sid}

Update the monthly shipment information for subscriber identified by {uid}. {sid} is a shipment that hasn't been delivered yet.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {sid} not found or invalid.

Resource URL

/sub/{uid}/shipments/{sid}

Parameters

None.

Example Request

	
  PUT http://localhost:8080/vin/sub/345/shipments/139

Here is data being PUT 

  
  {
    "delivery_day": "Tue",
    "time_of_day": "AM"
  }

Example Response

There is no body to this response.

GET /sub/{uid}/shipments/{sid}/notes

Returns an array of notes IDs for the subscriber {sid} and shipment {sid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {sid} not found or invalid.

Resource URL

/sub/{uid}/shipments/{sid}/notes

Parameters

None. In a future incarnation of this project, parameters may include a start and end date.

Example Request

	
  GET http://localhost:8080/vin/sub/345/shipments/139/notes

Example Response


  {
    "notes": [
      {
        "id": 790,
        "date": "14-Feb-2015",
        "content": "The Mission is a fantastic red."
      }
    ]
  }

POST /sub/{uid}/shipments/{sid}/notes

Creates a new note for the {sid} shipment. Returns the ID for the newly created note.

HTTP response codes: 201 (Created), 'Location' header with link to /sub/{uid}/shipments/{sid}/notes{nid} containing new ID. 404 (Not Found), if {uid} not found or invalid OR if {sid} not found or invalid.

Resource URL

/sub/{uid}/shipments/{sid}/notes

Parameters

content (required): the note content.

Example Request

	
  POST http://localhost:8080/vin/sub/345/shipments/139

Here is the data being POST-ed. 


  {
    "content": "I love this Dona Paula Black Label. Great after taste, fantastic finish."
  }

Example Response


  {
    "id": 791
  }

GET /sub/{uid}/shipments/{sid}/notes/{nid}

Returns the detail for shipment note identified by {nid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {sid} not found or invalid OR if {nid} not found or invalid.

Resource URL

/sub/{uid}/shipments/{sid}/notes/{nid}

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/sub/345/shipments/139/notes/791

Example Response


  {
    "date": "15-Mar-2015",
    "content": "I love this Dona Paula Black Label. Great after taste, fantastic finish."
  }

PUT /sub/{uid}/shipments/{sid}/notes/{nid}

Updates the content of note {nid}.

HTTP response code: 200 (OK) or 204 (No Content). 404 (Not Found), if {uid} not found or invalid OR if {sid} not found or invalid OR if {nid} not found or invalid.

Resource URL

/sub/{uid}/shipments/{sid}/notes/{nid}

Parameters

content (required): the note content.

Example Request

	
  PUT http://localhost:8080/vin/sub/345/shipments/139/notes/791

Here is the data being PUT. 


  {
    "content": "I love this Dona Paula Black Label. Great after taste, fantastic finish. Great ratings all around!"
  }

Example Response

There is no body for this response.

DELETE /sub/{uid}/shipments/{sid}/notes/{nid}

Deletes the note identified by {nid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {sid} not found or invalid OR if {nid} not found or invalid.

Resource URL

/sub/{uid}/shipments/{sid}/notes/{nid}

Parameters

None.

Example Request

	
  DELETE http://localhost:8080/vin/sub/345/shipments/139/notes/791

Example Response

There is no body for this response.

GET /sub/{uid}/wines

Returns an array of wine IDs shipped to this subscriber {uid}. For each wine include the label name.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid.

Resource URL

/sub/{uid}/wines

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/sub/345/wines

Example Response

To be posted soon.

GET /sub/{uid}/wines/{wid}

Returns detail for the wine {wid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {wid} not found or invalid OR if {wid} refers to a wine that was never shipped to {uid}.

Resource URL

/sub/{uid}/wines/{wid}

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/sub/345/wines/123

Example Response

To be posted soon.

GET /sub/{uid}/wines/{wid}/notes

Returns an array of note IDs created by {uid} for wine {wid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {wid} not found or invalid OR if {wid} refers to a wine that was never shipped to {uid}.

Resource URL

/sub/{uid}/wines/{wid}/notes

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/sub/345/wines/123/notes

Example Response

To be posted soon.

POST /sub/{uid}/wines/{wid}/notes

Creates a note for wine {wid}.

HTTP response codes: 201 (Created), 'Location' header with link to /sub/{uid}/wines/{wid}/notes/{nid} containing new ID. 404 (Not Found), if {uid} not found or invalid OR if {wid} not found or invalid OR if {wid} refers to a wine that was never shipped to {uid}.

Resource URL

/sub/{uid}/wines/{wid}/notes

Parameters

None.

Example Request

	
  POST http://localhost:8080/vin/sub/345/wines/123/notes

Example Response

To be posted soon.

GET /sub/{uid}/wines/{wid}/notes/{nid}

Returns the detail of note {nid} created by {uid} for wine {wid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {wid} not found or invalid.

Resource URL

/sub/{uid}/wines/{wid}/notes/{nid}

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/sub/345/wines/123/notes/837

Example Response

To be posted soon.

PUT /sub/{uid}/wines/{wid}/notes/{nid}

Update note {nid} created by {uid} for wine {wid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {wid} not found or invalid.

Resource URL

/sub/{uid}/wines/{wid}/notes/{nid}

Parameters

content (required): the note content.

Example Request

	
  PUT http://localhost:8080/vin/sub/345/wines/123/notes/837

Example Response

To be posted soon.

DELETE /sub/{uid}/wines/{wid}/notes/{nid}

Remove note {nid} created by {uid} for wine {wid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {wid} not found or invalid.

Resource URL

/sub/{uid}/wines/{wid}/notes/{nid}

Parameters

None.

Example Request

	
  DELETE http://localhost:8080/vin/sub/345/wines/123/notes/837

Example Response

To be posted soon.

GET /sub/{uid}/wines/{wid}/rating

Get the rating for {wid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {wid} not found or invalid.

Resource URL

/sub/{uid}/wines/{wid}/rating

Parameters

None.

Example Request

	
  PUT http://localhost:8080/vin/sub/345/wines/123/rating

Example Response

To be posted soon.

POST /sub/{uid}/wines/{wid}/rating

Submit a rating for {wid}.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid OR if {wid} not found or invalid.

Resource URL

/sub/{uid}/wines/{wid}/rating

Parameters

None.

Example Request

	
  POST http://localhost:8080/vin/sub/345/wines/123/rating

Example Response

To be posted soon.

GET /sub/{uid}/delivery

Returns delivery information for {uid}, e.g. day of the week and AM/PM.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid.

Resource URL

/sub/{uid}/delivery

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/sub/345/delivery

Example Response

	
  {
    "dow": "Fri",
    "tod": "AM"
  }

PUT /sub/{uid}/delivery

Updates delivery information for {uid}, e.g. day of the week and AM/PM.

HTTP response code: 200 (OK). 404 (Not Found), if {uid} not found or invalid.

Resource URL

/sub/{uid}/delivery

Parameters

dow (required): day of the week for delivery; valid values are Mon, Tue, Wed, Thu, Fri, Sat.

tod (required): time of day; valid values are AM, PM.

Example Request

	
  PUT http://localhost:8080/vin/sub/345/delivery

Here is the data being PUT. 

	
  {
    "dow": "Fri",
    "tod": "PM"    
  }

Example Response

There is no body for this response.

Admin

POST /admin

Creates a new administrator.

HTTP response codes: 201 (Created), 'Location' header with link to /admin{aid} containing new ID.

Resource URL

/admin

Parameters

name (required): e.g. Alice Admin

Example Request

	
  POST http://localhost:8080/vin/admin

Here is the data being POST-ed. 

	
  {
    "name": "Alice Admin"
  }

Example Response


  {
    "id": 617
  }

GET /admin

Returns an array of administrator IDs.

HTTP response code: 200 (OK). 404 (Not Found).

Resource URL

/admin

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/admin

Example Response


  {
      "admins": [
          {
              "id": 613,
              "name": "Default Admin"
          },
          {
              "id": 617,
              "name": "Alice Admin"
          }
      ]
  }

PUT /admin/{aid}

Updates information for {aid}.

HTTP response code: 200 (OK). 404 (Not Found), if {aid} not found or invalid.

Resource URL

/admin{aid}

Parameters

name (required).

Example Request

	
  PUT http://localhost:8080/admin/613

Here is the data being PUT. 

	
  {
    "name": "Bob Admin"  
  }

Example Response

There is no body for this response.

GET /admin/{aid}

Returns detailed information for the administrator {aid}.

HTTP response code: 200 (OK). 404 (Not Found).

Resource URL

/admin/{aid}

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/admin/613

Example Response


  {
    "id": 617,
    "name": "Alice Admin",
    "create_date": "20140413",
    "created_by": 613    
  }

GET /admin/revenue

Returns the wine club revenue since the beginning of time, unless a start and/or end date are specified.

HTTP response code: 200 (OK).

Resource URL

/admin/revenue[?start=YYYYMMDD&end=YYYYMMDD]

Parameters

start (optional): a date in YYYYMMDD format.

end (optional): a date in YYYYMMDD format.

Example Request

	
  GET http://localhost:8080/vin/admin/revenue?start=20150302&end=20150317

Example Response


  {
    "units_delivered": 98,
    "units_returned": 1,
    "wine_revenue": 5819.03,
    "delivery_revenue": 582.97
  }

GET /admin/monthly_selection

Returns an array of monthly selections IDs with month information.

HTTP response code: 200 (OK). 404 (Not Found).

Resource URL

/admin/monthly_selection

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/admin/monthly_selection

Example Response


  {
    "monthly_selection": [
      {
        "id": 853,
        "selection_month": "Feb/2015",
        "type": "AR"
      },
      {
        "id": 854,
        "selection_month": "Feb/2015",
        "type": "AW"
      },
      {
        "id": 855,
        "selection_month": "Feb/2015",
        "type": "RW"
      },
      {
        "id": 862,
        "selection_month": "Mar/2015",
        "type": "AR"
      },
      {
        "id": 863,
        "selection_month": "Mar/2015",
        "type": "AW"
      },
      {
        "id": 864,
        "selection_month": "Mar/2015",
        "type": "RW"
      }
    ]  
  }

POST /admin/monthly_selection

Creates a new monthly selection.

HTTP response codes: 201 (Created), 'Location' header with link to /admin/{mid} containing the newly created id.

Resource URL

/admin/monthly_selection

Parameters

type (required): e.g. AR, AW, RW.

selection_month (required): the month for which the selection is created, MMM/YYYY format

wines (required): an array of wines that are part of this monthly selection.

Example Request

	
  POST http://localhost:8080/vin/admin/monthly_selection

Here is the data being POST-ed. 

	
  {
    "type": "AR",
    "selection_month": "Feb/2015",
    "wines": [
      {
          "variety": "RED",
          "wine_type": "TABLE",
          "label_name": "The Mission",
          "grape": "Merlot",
          "region": "Napa",
          "country": "USA",
          "maker": "Sterling",
          "year": "2014"
      },
      {
          "variety": "RED",
          "wine_type": "TABLE",
          "label_name": "Joseph Phelps Cabernet Sauvignon 2012",
          "grape": "Cabernet Sauvignon",
          "region": "Napa",
          "country": "USA",
          "maker": "Joseph Phelps",
          "year": "2012"
      },
      {
          "variety": "RED",
          "wine_type": "TABLE",
          "label_name": "Round Pond Estate Rutherford",
          "grape": "Cabernet Sauvignon",
          "region": "Napa",
          "country": "USA",
          "maker": "Rutherford",
          "year": "2014"
      },
      {
          "variety": "RED",
          "wine_type": "TABLE",
          "label_name": "Dona Paula Black Label",
          "grape": "Bordeaux",
          "region": "",
          "country": "Argentina",
          "maker": "Dona Paula",
          "year": "2013"
      },
      {
          "variety": "RED",
          "wine_type": "TABLE",
          "label_name": "Schug Sonoma Coast Pinot Noir",
          "grape": "Pinot Noir",
          "region": "Sonoma Valley",
          "country": "USA",
          "maker": "Walter Schug",
          "year": "2013"
      },
      {
          "variety": "RED",
          "wine_type": "TABLE",
          "label_name": "Caymus Special Selection Cabernet Sauvignon",
          "grape": "Cabernet Sauvignon",
          "region": "Napa Valley",
          "country": "USA",
          "maker": "Charles F. Wagner",
          "year": "2014"
      }
    ]
  }

Example Response


  {
    "id": 853
  }

GET /admin/monthly_selection/{mid}

Returns detailed information about the monthly selection identified by {mid}.

HTTP response code: 200 (OK). 404 (Not Found), if {mid} not found or invalid.

Resource URL

/admin/monthly_selection/{mid}

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/admin/monthly_selection/853

Example Response


  {
    "id": 853,
    "selection_month": "Feb/2015",
    "type": "AR",
    "create_date": "20150115",
    "created_by": 613,
    "wines": [
        {
            "id": 123,
            "label_name": "The Mission"
        },
        {
            "id": 124,
            "label_name": "Joseph Phelps Cabernet Sauvignon 2012"
        },
        {
            "id": 125,
            "label_name": "Round Pond Estate Rutherford"
        },
        {
            "id": 126,
            "label_name": "Dona Paula Black Label"
        },
        {
            "id": 127,
            "label_name": "Schug Sonoma Coast Pinot Noir"
        },
        {
            "id": 128,
            "label_name": "Caymus Special Selection Cabernet Sauvignon "
        }
    ]
  }

Delivery Partner

GET /partner

Returns an array of subscribers to whom a monthly selection needs to be delivered.

HTTP response code: 200 (OK). 404 (Not Found).

Resource URL

/partner

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/partner

Example Response


  {
    "deliver_to": [
      {
        "name": "Jane Doe",
        "phone": "123-456-7890",
        "email": "jane.doe@example.com",
        "address": {
          "street": "123 Main ST, Apt 2F",
          "city": "Anytown",
          "state": "Anystate",
          "zip": "12345"
        },
        "dow": "Mon",
        "tod": "PM",
        "type": "AR"      
      },
      {
        "name": "John Smith",
        "phone": "312-456-7890",
        "email": "jsmith@example.com",
        "address": {
          "street": "200 West 31st Street, Apt 1R",
          "city": "Chicago",
          "state": "IL",
          "zip": "60616"
        },
        "dow": "",
        "tod": "PM", 
        "type": "AW"     
      }
    ]
  }

POST /receipt

Creates a delivery receipt.

HTTP response codes: 201 (Created), 'Location' header with link to /receipt/{rid} containing the newly created id.

Parameters

name (required): the name of the person receiving the delivery.

Example Request

	
  POST http://localhost:8080/vin/receipt

Here is the data being POST-ed. 

  
  {
    "name": "Anna Kosta"
  }

Example Response


  {
    "id": 907
  }

GET /receipt

Returns an array of receipts.

HTTP response code: 200 (OK). 404 (Not Found).

Resource URL

/receipt

Parameters

None for this project. In a commercial product you'd probably want to have a query string such that you return only receipts that match the query string, and/or a start and end date to narrow down the number of receipts you're getting back from the server.

Example Request

	
  GET http://localhost:8080/vin/receipt

Example Response


  {
    "receipts": [
      {
        "id": 901,
        "date": "20150213",
        "subscriber": 345,
        "name": "Jane Doe"
      },
      {
        "id": 907,
        "date": "20150213",
        "subscriber": 361,
        "name": "Sam Brown"
      }
    ]
  }

GET /receipt/{rid}

Get detail information for the delivery receipt identified by {rid}.

HTTP response code: 200 (OK). 404 (Not Found).

Resource URL

/receipt/{rid}

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/receipt/907

Example Response


  {
        "id": 907,
        "date": "20150213",
        "time": "10:12 AM",
        "subscriber": 361,
        "name": "Sam Brown",
        "received_by": "Anna Kosta"
  }

Other

GET /wines/{wid}

Returns detailed information for the wine identified by {wid}.

HTTP response code: 200 (OK). 404 (Not Found).

Resource URL

/wines/{wid}

Parameters

None.

Example Request

	
  GET http://localhost:8080/vin/wines/127

Example Response


  {
    "id": 127,
    "variety": "RED",
    "wine_type": "TABLE",
    "label_name": "Schug Sonoma Coast Pinot Noir",
    "grape": "Pinot Noir",
    "region": "Sonoma Valley",
    "country": "USA",
    "maker": "Walter Schug",
    "year": "2013",
    "ratings_count": 37,
    "rating": 4.8
  }
Last update: Apr 14, 2015 Virgil Bistriceanu cs445 Computer Science
$Id: project-api.html,v 1.6 2015/04/14 21:30:51 virgil Exp $