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:

  • email
  • password (plain)

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:

  • success
  • exception

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:

  • userid
  • stuffid

Data returned on "success":

  • null

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:

  • success
  • exception

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


Last edited Sep 21, 2013 at 2:49 AM by duybkict, version 22

Comments

No comments yet.