-
Notifications
You must be signed in to change notification settings - Fork 0
/
API.txt
62 lines (53 loc) · 4.67 KB
/
API.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
Warehouse Server App API
General Formatting
hierarchical URL: /<category>/<product>
Query Strings: place ? at the end of the hierarchical URL followed by the desired parameters, relevant parameters for each method are listed under the method heading below. Extra parameters will be ignored.
Responses are formatted as JSON objects, all methods will return a JSON object of the category operated on or requested with the contents included, if there is no category the entire inventory will be returned as a nested json object (e.g. {<category>:{<item>:<quantity>}}).
General Errors:
400 Bad Request "path too long" - there are too many "/" to the hierarchical portion of the URL
400 Bad Request "specified method <method> is not valid" - you used a HTTP method other than GET, PUT, POST or DELETE, these are the only valid methods for this API
Displaying stock
Use HTTP GET
Hierarchical URL is used to specify desired resource
the base URL will return the entire stock
/<category>/<product> will return the quantity of the product
/<category> will return all products with quantities inside the specified category
Parameters:
max=<int> - only returns items with stocks below the specified value, can be run with min parameter as well, will be ignored if the item is specified.
min=<int> - only returns items with stocks above the specified value, can be run with max parameter as well, will be ignored if the item is specified.
prefix= true or false - allows you to specify that the item string is only the start of the item or items desired, will return all matches starting with the requested string in <product>, will be ignored if there is no item specified.
Errors:
Status Code: 404 Content: "category not found" - the specified category does not exist in the database file
Status Code: 404 "item not found" - the specified item was not found in the selected category
Status Code: 400 'Option parameter was incorrectly specified' - prefix was specified as something other than true or false
Restocking/Selling items (increment and decrement):
Use HTTP PUT
a category and item must be specified in the hierarchical path e.g. /animals/giraffe
parameters:
option=<increment OR decrement> (required)
quant=<int> (defaults to 0)
Errors:
Status Code: 404 Content: "item does not exist" - the chosen item does not exist or you only specified a category, no item
Status Code: 400 Content: "negative quantity error" - occurs when a decrement operation would leave a stock below zero, does not change the stock of this product
Status Code: 400 Content: "invalid option, choose increment or decrement" - the option parameter must be set to either 'increment' or 'decrement'
"please include the option parameter in your query string and a path to an item, not a category" - the option parameter was excluded in your URL, this parameter is required for a POST or the path was too short
Adding products:
Use HTTP POST
A new category and product can be specified here. If an existing category with a new product is specified the product will be added to this category without effecting the previous entries. If there is an exact match of product and category, the old product will be overwritten with the new quantity.
Specify the desired category using the hierarchical URL e.g. /<category>?<querystring>
Include the desired items and their quantities in the HTTP body, formatted as JSON objects with item name as the key and the quantity as the value (ensure that the inner quotes are double quotes).
You can add as many items as you like but you can only add to one category at a time.
Errors:
Status Code: 200 Content: "category exists" - when adding a category without an item this will be displayed if the specified category already exists in the database file.
Status Code: 400 Content: "specify category and item" - occurs when both category and item are empty, this is a meaningless operation, you can not create a new root directory
Status Code: 400 Content: "quantity must be positive" - you have attempted to add an item with a negative quantity, causing a failure
Deleting products:
Use HTTP DELETE
Hierarchical URL is used to specify which resource will be deleted
/<category>/<product> will delete the specified item
/<category> will delete the specified category
/ deleting root is not allowed
Errors:
Status Code: 404 Content: "item does not exist" - the specified item does not exist within the specified category, no changes were made
Status Code: 404 Content: "category does not exist" - the specified category does not exist in the database, no changes were made
Status Code: 400 Content: "deleting the entire database is not allowed" - no category or item specified, this is not a legal operation