Overview
Guide material for API web service using for Structured Programming mini project development process
All the API service will be called via a request (GET, POST) from client side (GET method is available for all services just for development, testing and debugging purposes). Each API service returns data in form of an json array, each request parameter's
name must be in lowercase, no special character
Note: the return data is always in form of an json array. Conventionally, the first object is the type of the result ("success", "failure" or "exception"), the next object(s)
is the details of data returned.
- "success" is returned when execute an operation successfully, no error occurred.
- "failure" is return when a logic error, input validation error... occurred.
- "exception" is return when the system caught an exception.
Note: data type DateTime is always returned in format "yyyy-MM-ddThh:mm:ss.SSS"
I. User Account
a) Log In
Log into an existing user account with email and password. Possible results:
- success
- failure
- exception
Request params:
Data returned on "success"
- Id
- Email
- Firstname
- Lastname
- TrustRank
- Properties
- CreatedDateTime
- ModifiedDateTime
Possible errors on "failure"
- Login failed (wrong email or password)
A valid request:
http://<host_name>/API/UserAccount/LogIn?email=tranquangduy@gmail.com&password=123456
b) Register
Register new user account using some basic personal information. Possible results:
Request params:
- email
- password (plain)
- firstname
- lastname
Data returned on "success"
- Id
- Email
- Firstname
- Lastname
- TrustRank
- Properties
- CreatedDateTime
- ModifiedDateTime
A valid request:
http://<host_name>/API/UserAccount/Register?email=new@gmail.com&password=new&firstname=new&lastname=new
c) Edit
Edit User Account details by giving a specific user id and necessary account info. Possible results:
- success
- failure
- exception
Request params:
- id
- email (optional)
- password (plain, optional)
- firstname (optional)
- lastname (optional)
- trustrank (optional)
- properties (optional)
Data returned on "success"
- Id
- Email
- Firstname
- Lastname
- TrustRank
- Properties
- CreatedDateTime
- ModifiedDateTime
Possible errors on "failure":
- User Account does not exist
- Validation error: trust rank is not between 0 and 5
A valid request:
http://<host_name>/API/UserAccount/Edit?Id=8A5E25A9-8DFF-4C8F-A736-8527FFCE6CF2&firstname=editted
II. User Stuff
a) Get
Get all stuff belonging to a specific user account. Possible results:
- success
- failure
- exception
Request params:
- userid
- where (optional)
- order (optional)
- offset (optional)
- limit (optional)
Data returned on "success": list of stuffs, each stuff has all the following properties:
- Id
- UserId
- Name
- Quantity
- Description
- Properties
- CreatedDateTime
- ModifiedDateTime
- Category (json category object)
- Id
- ParentId
- Name
- Description
- Properties
- CreatedDateTime
- ModifiedDateTime
- StuffPrices (json array of prices)
- StuffId
- CurrencyId
- CurrencyType (USD, VND...)
- UnitPrice
Possible errors on "failure":
- User Account does not exist
A valid request:
http://<host_name>/API/UserStuff/Get?Id=8A5E25A9-8DFF-4C8F-A736-8527FFCE6CF2&where=quantity=5&order=Name&offset=2&limit=10
b) Insert
Insert stuff belonging to a specific user account. Possible results:
- success
- failure
- exception
Request params:
- userid
- name
- description (optional)
- quantity (optional, default = 1)
Data returned on "success": last inserted stuff
- Id
- UserId
- Name
- Quantity
- Description
- Properties
- CreatedDateTime
- ModifiedDateTime
- Category (json category object)
- Id
- ParentId
- Name
- Description
- Properties
- CreatedDateTime
- ModifiedDateTime
- StuffPrices (json array of prices)
- StuffId
- CurrencyId
- CurrencyType (USD, VND...)
- UnitPrice
Possible errors on "failure":
- User Account does not exist
- Validation error: quantity is not greater than or equal to zero.
A valid request: http://<host_name>/API/UserStuff/Insert?Id=8A5E25A9-8DFF-4C8F-A736-8527FFCE6CF2&name=iphone5&description=smartphone
c) Update
Update details of an user stuff with information provided in request. Possible results:
- success
- failure
- exception
Request params:
- userid
- stuffid
- name (optional)
- description (optional)
- properties (optional)
- quantity (optional)
Data returned on "success":
- Id
- UserId
- Name
- Quantity
- Description
- Properties
- CreatedDateTime
- ModifiedDateTime
- Category (json category object)
- Id
- ParentId
- Name
- Description
- Properties
- CreatedDateTime
- ModifiedDateTime
- StuffPrices (json array of prices)
- StuffId
- CurrencyId
- CurrencyType (USD, VND...)
- UnitPrice
Possible errors on "failure":
- User Account does not exist
- Validation error: quantity is not greater than or equal to zero
- Authorization error: try to edit stuff details of other user account
- User Stuff does not exist
A valid request: http://<host_name>/API/UserStuff/Update?Id=8A5E25A9-8DFF-4C8F-A736-8527FFCE6CF2&name=iphone5edited&description=new smartphone
d) Delete
Delete an existing user stuff. Possible results:
- success
- failure
- exception
Request params:
Data returned on "success":
Possible errors on "failure":
- User Account does not exist
- Authorization error: try to edit stuff details of other user account
- User Stuff does not exist
A valid request: http://<host_name>/API/UserStuff/Delete?Id=8A5E25A9-8DFF-4C8F-A736-8527FFCE6CF2&stuffid=1
e) SetPrice
Set price for an user stuff. Possible results:
- success
- failure
- exception
Request params:
- userid
- stuffid
- unitPrice
- unitType
Data returned on "success" - last edited user stuff:
- Id
- UserId
- Name
- Quantity
- Description
- Properties
- CreatedDateTime
- ModifiedDateTime
- Category (json category object)
- Id
- ParentId
- Name
- Description
- Properties
- CreatedDateTime
- ModifiedDateTime
- StuffPrices (json array of prices)
- StuffId
- CurrencyId
- CurrencyType (USD, VND...)
- UnitPrice
Possible errors on "failure":
- User Account does not exist
- Authorization error: try to edit stuff details of other user account
- User Stuff does not exist
- Type of currency does not exist
A valid request: http://<host_name>/API/UserStuff/SetPrice?Id=8A5E25A9-8DFF-4C8F-A736-8527FFCE6CF2&stuffid=1&unitprice=100&unittype=USD
II. Shopping
a) Get
Get all stuffs for shopping. Possible results:
Request params:
- where (optional)
- order (optional)
- offset (optional)
- limit (optional)
Data returned on "success": list of stuffs, each stuff has all the following properties:
- Id
- UserId
- Name
- Quantity
- Description
- Properties
- CreatedDateTime
- ModifiedDateTime
- Category (json category object)
- Id
- ParentId
- Name
- Description
- Properties
- CreatedDateTime
- ModifiedDateTime
- StuffPrices (json array of prices)
- StuffId
- CurrencyId
- CurrencyType (USD, VND...)
- UnitPrice
A valid request:
http://<host_name>/API/Shopping/Get?where=quantity=5&order=Name&offset=2&limit=10