Skip to content

Rest API Functional Specs

Jump to bottom
Yazeed Bzadough edited this page Mar 15, 2016 · 10 revisions

##Rest API Functionality Specs ####This document describes the functional specifications for our Python Rest API.

#####Our method of authentication is JSON Web Tokens (JWT). This is a token that must be passed in to the request headers in order to access any protected API route. All routes will be labeled either public or protected

##Authentication ###/api/auth - Authenticate: POST (public)

####Upon validation, returns a JWT that allows access our API's protected routes.

  • POST- Get a JWT
    • Request: body: { email: "yazeed@test.com", password: "yazeed" }
    • Response: { success: true, token: token }

##Users ###/api/users - all users: POST (public), GET (protected) ####Create new users, and retrieve all existing ones.

  • POST- Create a new user
    • Request:
      • body: { email: "yazeed@test.com", password: "yazeed", firstName: "Yazeed", lastName: "Bzadough" }
    • Response: { success: true, message: "User has been created", dateJoined: "3/13/2016" }
  • GET- Retrieve all users in an array
    • Request:
      • headers: { token: "validJWT" }
    • Response: { success: true, users: [allUsers] }

###/api/users/:email - single user: GET, PUT, DELETE (all protected) ####Find a user by email, and retrieve, edit, or delete them.

  • GET- Retrieve a user by email
    • Request:
      • headers: { token: "validJWT" }
      • urlParams: { email: yazeed@test.com }
    • Response: { success: true, user: user }
  • PUT- Edit a user's information
    • Request:
      • body: { token: "validJWT", password: "newPassword" }
      • urlParams: { email: "yazeed@test.com" }
    • Response: { success: true, message: "User successfully updated", datePassModified: "1457907282196" }
  • Delete- Delete a user
    • Request:
      • headers: { token: "validJWT" }
      • urlParams: { email: "yazeed@test.com" }
    • Response: { success: true, message: "User successfully deleted" }

##Transactions ###/api/transactions - all transactions: GET (protected) ####Create new transactions, and retrieve all existing ones.

  • GET- Retrieve all transactions in an array
    • Request:
      • headers: { token: "validJWT" }
    • Response: { success: true, transactions: [allTransactions] }

###/api/:email/transactions - user's transactions: GET, POST (all protected) ####Create a new transaction for a user, or retrieve all of their existing ones.

  • GET- Retrieve all of a user's transactions in an array
    • Request:
      • headers: { token: "validJWT" }
      • urlParams: { email: "yazeed@test.com" }
    • Response: { success: true, transactions: [allTransactions] }
  • POST- Create a new transaction under this user's account
    • Request:
      • urlParams: { email: "yazeed@test.com" }
      • body: { token: "validJWT", transaction: { name: "full-time job", type: "credit", amount: "1000", date: "1457907282196", merchantName: "Beacon One", description: "Bi-weekly salary from work", frequency: "biweekly" }}
    • Response: { success: true, message: "Transaction has been created" }

###/api/:email/transactions/:uuid - single transaction: GET, PUT, DELETE (all protected) ####Find a single transaction belonging to a user with its unique identifier

  • GET- Retrieve a single transaction
    • Request:
      • headers: { token: "validJWT" },
      • urlParams: { email: "yazeed@test.com", uuid: "uniqueID" }
    • Response: { success: true, transaction: { transaction } }
  • PUT- Edit a transaction
    • Request:
      • body: { token: "validJWT", transaction: { name: "part-time job", merchantName: "McDonald's", amount: "450", frequency: "weekly" } }
      • urlParams: { email: "yazeed@test.com" }
    • Response: { success: true, message: "Transaction successfully updated" }
  • Delete- Delete a transaction
    • Request:
      • headers: { token: "validJWT" },
      • urlParams: { email: "yazeed@test.com", uuid: "uniqueID" }
    • Response: { success: true, message: "Transaction successfully deleted" }

##Budgets ###/api/budgets - all budgets: GET (protected) ####Create new budgets, and retrieve all existing ones.

  • GET- Retrieve all budgets in an array
    • Request:
      • headers: { token: "validJWT" }
    • Response: { success: true, budgets: [all budgets] }

###/api/:email/budgets - user's budgets: GET, POST (all protected) ####Create a new budget for a user, or retrieve all of their existing ones.

  • GET- Retrieve all of a user's budgets in an array
    • Request:
      • headers: { token: "validJWT" }
      • urlParams: { email: "yazeed@test.com" }
    • Response: { success: true, budgets: [all budgets] }
  • POST- Create a new budgets under this user's account
    • Request:
      • urlParams: { email: "yazeed@test.com" }
      • body: { token: "validJWT", budget: { name: "groceries", description: "monthly budget for groceries", startDate: "1457907282196", endDate: "1457909282196", targetAmount: "350", currentAmount: "0", downPayment: "0" }}
    • Response: { success: true, message: "Budget has been created" }

###/api/:email/budgets/:uuid - single budget: GET, PUT, DELETE (all protected) ####Find a single budget belonging to a user with its unique identifier

  • GET- Retrieve a single budget
    • Request:
      • headers: { token: "validJWT" },
      • urlParams: { email: "yazeed@test.com", uuid: "uniqueID" }
    • Response: { success: true, budget: { budget } }
  • PUT- Edit a budget
    • Request:
      • body: { token: "validJWT", budget: { name: "travel", description: "monthly travel expenses", targetAmount: "300" } }
      • urlParams: { email: "yazeed@test.com" }
    • Response: { success: true, message: "Budget successfully updated" }
  • Delete- Delete a budget
    • Request:
      • headers: { token: "validJWT" },
      • urlParams: { email: "yazeed@test.com", uuid: "uniqueID" }
    • Response: { success: true, message: "Budget successfully deleted" }

##Goals ###/api/goals - all goals: GET (protected) ####Create new goals, and retrieve all existing ones.

  • GET- Retrieve all goals in an array
    • Request:
      • headers: { token: "validJWT" }
    • Response: { success: true, goals: [all goals] }

###/api/:email/goals - user's goals: GET, POST (all protected) ####Create a new goals for a user, or retrieve all of their existing ones.

  • GET- Retrieve all of a user's goals in an array
    • Request:
      • headers: { token: "validJWT" }
      • urlParams: { email: "yazeed@test.com" }
    • Response: { success: true, goals: [all goals] }
  • POST- Create a new goal under this user's account
    • Request:
      • urlParams: { email: "yazeed@test.com" }
      • body: { token: "validJWT", goal: { name: "Xbox One", targetDate: "1458005130050", targetAmount: "300", currentAmount: "0", createdBy: "yazeed@test.com", duration: "long", purchaseLink: "http://www.amazon.com/Xbox-One-1TB-Elite-Console-Bundle/dp/B014PZTAME/ref=sr_1_4?s=videogames&ie=UTF8&qid=1458005211&sr=1-4&keywords=xbox+one", public: false }}
    • Response: { success: true, message: "Goal has been created" }

###/api/:email/goals/:uuid - single goal: GET, PUT, DELETE (all protected) ####Find a single goal belonging to a user with its unique identifier

  • GET- Retrieve a single goal
    • Request:
      • headers: { token: "validJWT" },
      • urlParams: { email: "yazeed@test.com", uuid: "uniqueID" }
    • Response: { success: true, goal: { goal } }
  • PUT- Edit a goal
    • Request:
      • body: { token: "validJWT", goal: { name: "ps4", description: "Xbox Ones are lame", targetAmount: "350" } }
      • urlParams: { email: "yazeed@test.com" }
    • Response: { success: true, message: "Goal successfully updated" }
  • Delete- Delete a goal
    • Request:
      • headers: { token: "validJWT" },
      • urlParams: { email: "yazeed@test.com", uuid: "uniqueID" }
    • Response: { success: true, message: "Goal successfully deleted" }

##Wishes ###/api/wishes - all wishes: GET, POST (protected) ####Create new wishes, and retrieve all existing ones.

  • GET- Retrieve all wishes in an array
    • Request:
      • headers: { token: "validJWT" }
    • Response: { success: true, wishes: [all wishes] }

###/api/:email/wishes - user's wishes: GET, POST (all protected) ####Create a new wish for a user, or retrieve all of their existing ones.

  • GET- Retrieve all of a user's wishes in an array
    • Request:
      • headers: { token: "validJWT" }
      • urlParams: { email: "yazeed@test.com" }
    • Response: { success: true, wishes: [all wishes] }
  • POST- Create a new wish under this user's account
    • Request:
      • urlParams: { email: "yazeed@test.com" }
      • body: { token: "validJWT", wish: { name: "3D TV", merchantName: "Samsung", purchaseLink: "http://www.amazon.com/Samsung-UN65JS8500-65-Inch-Ultra-Smart/dp/B00U9U9GII/ref=sr_1_1?ie=UTF8&qid=1458006225&sr=8-1&keywords=samsung+3d+tv" } }
    • Response: { success: true, message: "wish has been created" }

###/api/:email/wishes/:uuid - single wish: GET, PUT, DELETE (all protected) ####Find a single wish belonging to a user with its unique identifier

  • GET- Retrieve a single wish
    • Request:
      • headers: { token: "validJWT" },
      • urlParams: { email: "yazeed@test.com", uuid: "uniqueID" }
    • Response: { success: true, wish: { wish } }
  • PUT- Edit a wish
    • Request:
      • body: { token: "validJWT", wish: { name: "4D TV", merchantName: "Samsung" } }
      • urlParams: { email: "yazeed@test.com" }
    • Response: { success: true, message: "wish successfully updated" }
  • Delete- Delete a wish
    • Request:
      • headers: { token: "validJWT" },
      • urlParams: { email: "yazeed@test.com", uuid: "uniqueID" }
    • Response: { success: true, message: "wish successfully deleted" }

##Tags ###/api/tags - all tags: GET, POST (all protected) ####Create a new tag, or retrieve all tags in an array

  • GET- Retrieve all tags
    • Request:
      • headers: { token: "validJWT" }
    • Response:
      • { success: true, tags: [all tags] }
  • POST- Create one or many tags
    • Request:
      • Single tag as an object:
        • body: { token: "validJWT", tag: { name: "food" } }
      • Or many tags as an array
        • body: { token: "validJWT", tag: [{ name: "food" }, { name: "travel" }, { name: "cell phone" }] }
    • Response: { success: true, message: "Tags successfully created" }

###/api/tags/:name - find a tag by name: GET, PUT, DELETE (all protected) ####Find a tag by name, and retrieve, edit, or delete them.

  • GET- Retrieve a tag by name
    • Request:
      • headers: { token: "validJWT" }
    • Response: { success: true, tag: tag }
  • PUT- Edit a tag
    • Request:
      • body: { token: "validJWT", password: "newPassword" }
      • urlParams: { email: "yazeed@test.com" }
    • Response: { success: true, message: "tag successfully updated" }
  • Delete- Delete a tag
    • Request:
      • headers: { token: "validJWT" }
    • Response: { success: true, message: "tag successfully deleted" }

##Emails ###/api/invite/:email - invite a user to sign up, or view an existing invite: POST (protected)

  • GET- View an existing invite
    • Request:
      • headers: { token: "validJWT" }
      • urlParams: { email: "ted@sample.com" }
    • Response:
      • If the user has accepted body: { success: true, accepted: true }
      • If the user has not yet accepted body: { success: true, accepted: false }
  • POST- Invite a user by email
    • Request:
      • body: { token: "validJWT", email: "ted@sample.com" }
    • Response: { success: true, message: "Email sent" }

##Friends ###/api/:email/friends - see all friends a user has, or add a friend: GET, POST (all protected)

  • GET- View a user's friends
    • Request:
      • headers: { token: "validJWT" }
      • urlParams: { email: "yazeed@sample.com" }
    • Response: { success: true, friends: [all friends] }
  • POST- Add a new friend
    • Request:
      • body: { token: "validJWT", email: "ted@sample.com" }
    • Response: { success: true, message: "Friend request sent" }

###/api/:email/friends/:friendEmail - view a pending request, or cancel it: GET, DELETE (all protected)

  • GET- View an existing request
    • Request:
      • headers: { token: "validJWT" }
      • urlParams: { email: "yazeed@sample.com", friendEmail: "ted@sample.com" }
    • Response:
      • If the user has accepted body: { success: true, accepted: true }
      • If the user has not yet accepted body: { success: true, accepted: false }
  • DELETE- Cancel a friend request
    • Request:
      • urlParams: { token: "validJWT", email: "yazeed@sample.com", friendEmail: "ted@sample.com" }
    • Response: { success: true, message: "Friend request cancelled" }

Clone this wiki locally