Skip to content

Files

Latest commit

5eea0c8 · Oct 23, 2021

History

History
474 lines (416 loc) · 16.3 KB

README.md

File metadata and controls

474 lines (416 loc) · 16.3 KB

Example Store API

Note: Most RESTful APIs are not truly RESTful, and this API is no exception.


Products API

GET /products

GET /v1/products

Retrieve a list of all Products within the database. We can provide query parameters to filter our results. The available filters are:

Field Description
id Search for products by Product ID.
name Search for products with a name that contain this search term.
description Search for products with a description that contain this search phrase.
category Search for products by Category name.
vendor Search for products by Vendor name.
minQuantity Filter for products with a quantity (qty in the DB) greater than or equal to this value.
maxQuantity Filter for products with a quantity (qty in the DB) leass than or equal to this value.
minCost Filter for products with a cost greater than or equal to this value.
maxCost Filter for products with a cost leass than or equal to this value.
minMSRP Filter for products with a msrp greater than or equal to this value.
maxMSRP Filter for products with a msrp leass than or equal to this value.
orderyBy Sort the products in order of: id, name, cost, msrp, quantity, category, and vendor.
reversed Sort in reverse order. Default: false.
limit Limit the number of results returned for pagination.
offset Offset to the start result for a paginated result.

Additional fields:

Field Description
chain If provided, filter using the previous request, in addition to the newly given parameters. A principle of REST is that each request is stateless. Every request is treated as new. No session, no history. So, this feature violates REST, however, I wanted to demonstrate the use of sesssions, so I've added it here.

Sample Response: GET /v1/products

{
  "version": "1.0",
  "rid": 4,
  "method": "GET",
  "uri": "/Module_B/v1/products",
  "length": 110,
  "search": {},
  "results": {
    "products": [
      {
        "id": "S10_1678",
        "name": "1969 Harley Davidson Ultimate Chopper",
        "description": "This replica features working kickstand, front suspension, gear-shift lever, footbrake lever, drive chain, wheels and steering. All parts are particularly delicate due to their precise scale and require special care and attention.",
        "category": "Motorcycles",
        "vendor": "Min Lin Diecast",
        "quantity": 7933,
        "cost": 48.81,
        "msrp": 95.7
      },
      {
        "id": "S10_2016",
        "name": "1996 Moto Guzzi 1100i",
        "description": "Official Moto Guzzi logos and insignias, saddle bags located on side of motorcycle, detailed engine, working steering, working suspension, two leather seats, luggage rack, dual exhaust pipes, small saddle bag located on handle bars, two-tone paint with chrome accents, superior die-cast detail , rotating wheels , working kick stand, diecast metal with plastic parts and baked enamel finish.",
        "category": "Motorcycles",
        "vendor": "Highway 66 Mini Classics",
        "quantity": 6625,
        "cost": 68.99,
        "msrp": 118.94
      },
      ...
    ]
  }
}

GET /products/<id>

GET /v1/products/<id>

Retrieve a specific Product with the given <id>.

Sample Response: GET /v1/products/S10_1678

{
  "version": "1.0",
  "rid": 1,
  "method": "GET",
  "uri": "/Module_B/v1/products/S10_1678",
  "result": {
    "id": "S10_1678",
    "name": "1969 Harley Davidson Ultimate Chopper",
    "description": "This replica features working kickstand, front suspension, gear-shift lever, footbrake lever, drive chain, wheels and steering. All parts are particularly delicate due to their precise scale and require special care and attention.",
    "category": "Motorcycles",
    "vendor": "Min Lin Diecast",
    "quantity": 7933,
    "cost": 48.81,
    "msrp": 95.7
  }
}

POST /products

POST /v1/products

Add one or more Product objects to the database, given as JSON.

Sample Request 1: POST /v1/products

{
  "id": "A320_2019",
  "name": "US Airways A320 Model Airplane",
  "description": "A replica scale model of the original Airbus A320-200 US Airways model aircraft. The US Airways A320 Model Airplane is crafted from pressure cast composite resin and is an impressive airplane gift. Our A320 US Airways Model Airplane arrives fully assembled and includes a display stand.",
  "category": "Planes",
  "vendor": "Min Lin Diecast",
  "quantity": 1000,
  "cost": 270.00,
  "msrp": 395.7
}

Sample Response 1: POST /v1/products

{
  "version": "1.0",
  "rid": 3,
  "method": "POST",
  "uri": "/Module_B/v1/products",
  "inserted": {
    "id": "A320_2019",
    "name": "US Airways A320 Model Airplane",
    "description": "A replica scale model of the original Airbus A320-200 US Airways model aircraft. The US Airways A320 Model Airplane is crafted from pressure cast composite resin and is an impressive airplane gift. Our A320 US Airways Model Airplane arrives fully assembled and includes a display stand.",
    "category": "Planes",
    "vendor": "Min Lin Diecast",
    "quantity": 1000,
    "cost": 270,
    "msrp": 395.7
  }
}

Sample Request 2: POST /v1/products

[
  {
    "id": "M20_5010",
    "name": "Full Stack Space Shuttle Endeavour Model",
    "description": "Our space shuttle Endeavour with full stack replica scale model is crafted after the original produced for NASA. The Endeavour had an orbiter designation of OV-105, and was the last space shuttle that was built. It ultimately took 25 flights. This Endeavour space shuttle with full stack model arrives completely assembled and has an attractive base for display.",
    "category": "Planes",
    "vendor": "Min Lin Diecast",
    "quantity": 1000,
    "cost": 410.00,
    "msrp": 595.7
  }, {
    "id": "M54_4003",
    "name": "Cessna 150/152 Model Airplane",
    "description": "This Cessna 150/152 Model Airplane is a replica scale model of the original Cessna 150/152 model aircraft. The Cessna 150/152 Model Airplane is crafted from wood and is an impressive aviation gift. Our Cessna 150/152 model aircraft arrives fully assembled and includes a display stand.",
    "category": "Planes",
    "vendor": "Min Lin Diecast",
    "quantity": 5780,
    "cost": 194.00,
    "msrp": 255.3
  }
]

Sample Response 2: POST /v1/products

{
  "version": "1.0",
  "rid": 4,
  "method": "POST",
  "uri": "/Module_B/v1/products",
  "length": 2,
  "inserted": {
    "products": [
      {
        "id": "M20_5010",
        "name": "Full Stack Space Shuttle Endeavour Model",
        "description": "Our space shuttle Endeavour with full stack replica scale model is crafted after the original produced for NASA. The Endeavour had an orbiter designation of OV-105, and was the last space shuttle that was built. It ultimately took 25 flights. This Endeavour space shuttle with full stack model arrives completely assembled and has an attractive base for display.",
        "category": "Planes",
        "vendor": "Min Lin Diecast",
        "quantity": 1000,
        "cost": 410,
        "msrp": 595.7
      },
      {
        "id": "M54_4003",
        "name": "Cessna 150/152 Model Airplane",
        "description": "This Cessna 150/152 Model Airplane is a replica scale model of the original Cessna 150/152 model aircraft. The Cessna 150/152 Model Airplane is crafted from wood and is an impressive aviation gift. Our Cessna 150/152 model aircraft arrives fully assembled and includes a display stand.",
        "category": "Planes",
        "vendor": "Min Lin Diecast",
        "quantity": 5780,
        "cost": 194,
        "msrp": 255.3
      }
    ]
  }
}

PUT /products/<id>

PUT /v1/products/<id>

Update the values in the specified Product, given as JSON.

Sample Request: PUT /v1/products/S700_3505

{
  "quantity": 556,
  "cost": 151.09
}

Sample Response: PUT /v1/products/S700_3505

{
  "version": "1.0",
  "rid": 7,
  "method": "PUT",
  "uri": "/Module_B/v1/products/S700_3505",
  "updated": {
    "id": "S700_3505",
    "name": "The Titanic",
    "description": "Completed model measures 19 1/2 inches long, 9 inches high, 3inches wide and is in barn red/black. All wood and metal.",
    "category": "Ships",
    "vendor": "Carousel DieCast Legends",
    "quantity": 556,
    "cost": 151.09,
    "msrp": 100.17
  }
}

DELETE /products/<id>

DELETE /v1/products/<id>

Delete the specified Product. Returns the delete record.

Sample Response: DELETE /v1/products/A320_2019

{
  "version": "1.0",
  "rid": 9,
  "method": "DELETE",
  "uri": "/Module_B/v1/products/A320_2019",
  "deleted": "A320_2019",
  "removed": {
    "id": "A320_2019",
    "name": "US Airways A320 Model Airplane",
    "description": "A replica scale model of the original Airbus A320-200 US Airways model aircraft. The US Airways A320 Model Airplane is crafted from pressure cast composite resin and is an impressive airplane gift. Our A320 US Airways Model Airplane arrives fully assembled and includes a display stand.",
    "category": "Planes",
    "vendor": "Min Lin Diecast",
    "quantity": 1000,
    "cost": 270,
    "msrp": 395.7
  }
}

Exceptions

Sample Exception:

{
  "version": "1.0",
  "rid": 10,
  "method": "DELETE",
  "uri": "/Module_B/v1/products/A320_2019",
  "exception": {
    "detailMessage": "No product exists with the given ID, use insert instead: A320_2019",
    "stackTrace": [
      {
        "declaringClass": "api.model.ProductsDAO",
        "methodName": "deleteProduct",
        "fileName": "ProductsDAO.java",
        "lineNumber": 278
      },
      {
        "declaringClass": "api.services.ProductsAPIService",
        "methodName": "doDeleteOne",
        "fileName": "ProductsAPIService.java",
        "lineNumber": 353
      },
      {
        "declaringClass": "api.services.ProductsAPIService",
        "methodName": "doDelete",
        "fileName": "ProductsAPIService.java",
        "lineNumber": 107
      },
      {
        "declaringClass": "javax.servlet.http.HttpServlet",
        "methodName": "service",
        "fileName": "HttpServlet.java",
        "lineNumber": 666
      },
      ...
    ],
    "suppressedExceptions": []
  }
}

Cart API

GET /cart

GET /v1/cart

Retrieve a list of all Products within the shopping cart.

Sample Response: GET /v1/cart

{
  "version": "1.0",
  "rid": 5,
  "method": "GET",
  "uri": "/Module_B/v1/cart",
  "length": 2,
  "cart": {
    "products": [
      {
        "id": "S10_1678",
        "name": "1969 Harley Davidson Ultimate Chopper",
        "description": "This replica features working kickstand, front suspension, gear-shift lever, footbrake lever, drive chain, wheels and steering. All parts are particularly delicate due to their precise scale and require special care and attention.",
        "category": "Motorcycles",
        "vendor": "Min Lin Diecast",
        "quantity": 7933,
        "cost": 48.81,
        "msrp": 95.7
      },
      {
        "id": "S10_2016",
        "name": "1996 Moto Guzzi 1100i",
        "description": "Official Moto Guzzi logos and insignias, saddle bags located on side of motorcycle, detailed engine, working steering, working suspension, two leather seats, luggage rack, dual exhaust pipes, small saddle bag located on handle bars, two-tone paint with chrome accents, superior die-cast detail , rotating wheels , working kick stand, diecast metal with plastic parts and baked enamel finish.",
        "category": "Motorcycles",
        "vendor": "Highway 66 Mini Classics",
        "quantity": 6625,
        "cost": 68.99,
        "msrp": 118.94
      }
    ]
  }
}

POST /cart/add

POST /v1/cart/add

Add all of the items to the cart that match the given search filter.

Field Description
chain If provided, add the products that match the previous request's filter. A principle of REST is that each request is stateless. Every request is treated as new. No session, no history. So, this feature violates REST, however, I wanted to demonstrate the use of sesssions, so I've added it here.
addAll Flag to permit adding all of the products in the store into the shopping cart.

This is not a RESTful endpoint. First, it uses POST which strictly speaking is not a RESTful HTTP method. Most RESTful APIs are not truly RESTful, and this API is no exception. It has been pointed out, "why not use PUT /cart instead?". However, the POST /cart/add feature is different semantically than PUT /cart. PUT /cart would create the cart, a new cart, but we want to add an item or items to the cart, the existing cart.

Sample request: POST /v1/cart/add

{"id": "S10_2016"}

Sample response: POST /v1/cart/add

{
  "version": "1.0",
  "rid": 7,
  "method": "POST",
  "uri": "/Module_B/v1/cart/add",
  "length": 1,
  "search": {
    "id": "S10_2016"
  },
  "added": {
    "products": [
      {
        "id": "S10_2016",
        "name": "1996 Moto Guzzi 1100i",
        "description": "Official Moto Guzzi logos and insignias, saddle bags located on side of motorcycle, detailed engine, working steering, working suspension, two leather seats, luggage rack, dual exhaust pipes, small saddle bag located on handle bars, two-tone paint with chrome accents, superior die-cast detail , rotating wheels , working kick stand, diecast metal with plastic parts and baked enamel finish.",
        "category": "Motorcycles",
        "vendor": "Highway 66 Mini Classics",
        "quantity": 6625,
        "cost": 68.99,
        "msrp": 118.94
      }
    ]
  }
}

POST /cart/remove

POST /v1/cart/remove

Remove all of the items to the cart that match the given search filter.

Field Description
chain If provided, remove the products that match the previous request's filter. A principle of REST is that each request is stateless. Every request is treated as new. No session, no history. So, this feature violates REST, however, I wanted to demonstrate the use of sesssions, so I've added it here.

This is not a RESTful endpoint. First, it uses POST which strictly speaking is not a RESTful HTTP method. Most RESTful APIs are not truly RESTful, and this API is no exception. It has been pointed out, "why not use DELETE /cart instead?". However, the POST /cart/remove feature is different semantically than DELETE /cart. DELETE /cart would delete the entire cart, but we want to just remove an item or some items from the cart and not delete whole thing.

Sample request: POST /v1/cart/remove

{"id": "S10_1678"}

Sample response: POST /v1/cart/remove

{
  "version": "1.0",
  "rid": 8,
  "method": "POST",
  "uri": "/Module_B/v1/cart/remove",
  "length": 1,
  "search": {
    "id": "S10_1678"
  },
  "removed": {
    "products": [
      {
        "id": "S10_1678",
        "name": "1969 Harley Davidson Ultimate Chopper",
        "description": "This replica features working kickstand, front suspension, gear-shift lever, footbrake lever, drive chain, wheels and steering. All parts are particularly delicate due to their precise scale and require special care and attention.",
        "category": "Motorcycles",
        "vendor": "Min Lin Diecast",
        "quantity": 7933,
        "cost": 48.81,
        "msrp": 95.7
      }
    ]
  }
}