cs445 Object Oriented Design and Programming

Content surrounded by [] is mandatory and will be replaced by the string literal identified. Possible insertion values:

Each resource type defined in this specification has a manager (or "entity set") that lives at the address /[type] where the [type] is the name of the resource type. For instance, the resource manager for the type asks will be found at: https://server/path/asks

Let's say that you deploy your application in a Tomcat container hosted locally, on your computer, and that tomcat has the default settings which means it will listen for requests at port 8080. The Service Base URL in this case is http://localhost:8080/bn/api. The resource manager for the type asks will be found at: http://localhost:8080/bn/api/asks.

Also, all data is in JSON format. A GET request will return JSON. A PUT or POST will submit a JSON document.

All use cases marked with (*) are not required as part of the final delivery for this project.

To make examples easier to read and to understand the API, we'll be using the following abbreviations throughout this document, instead of single generic id:

The following sections show the resource sets and, for each of them the use cases implemented.

You may want to check the Known Limitations section of this document that documents discrepancies between the requirements and the API.

Actors

Create account

POST /accounts

Creates an account and returns, in the header of the response, a 'Location' that points to the resource, i.e. /accounts/[uid] where [uid] is the newly assigned ID for the account.

HTTP response code:

201 (Created) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.

Resource URL

/accounts

Parameters

uid (required): empty value. The POST will create the resource and assign a unique and immutable value to 'uid'. Unique means no two resources, whether accounts, asks, gives, notes, etc. may have the same ID. Technically the 'uid' is not required, however it makes JSON to object coversion a lot simpler.

name (required): full name of the account holder.

address (required): a JSON representation of account holder's address.

phone (required): mobile phone number.

picture (required): for simplicity we'll just use a URL here.

is_active (required): account's status, true if active, false otherwise.

date_created (required): empty value. The POST will create the resource and assign a value to 'date_created'. Technically the 'date_created' field is not required since it will be provided by the server, however it makes JSON to object coversion a lot simpler. Once populated the value of "date_created" cannot be changed.

Example Request

      POST http://localhost:8080/bn/api/accounts/7

Here is data being POST-ed

      {
      	"uid": "",
      	"name": "John Smith",
      	"address": {
      		"street": "123 Main ST",
      		"zip": "60616"
      	},
      	"phone": "312-456-7890",
      	"picture": "http://example.com/images/john-smith.jpeg",
      	"is_active": false,
        "date_created": ""
      }

Example Response

      {
      	"uid": "7",
      	"name": "John Smith",
      	"address": {
      		"street": "123 Main ST",
      		"zip": "60616"
      	},
      	"phone": "312-456-7890",
      	"picture": "http://example.com/images/john-smith.jpeg",
      	"is_active": false,
        "date_created": "2022-03-12T17:12:26Z"
      }

Example Response when Something Went Wrong

Let's assume that the following data is being POST-ed

      {
      	"uid": "",
      	"name": "John Smith",
      	"address": {
      		"street": "123 Main ST",
      		"zip": ""
      	},
      	"phone": "312-456-7890",
      	"picture": "http://example.com/images/john-smith.jpeg",
      	"is_active": false,
        "date_created": ""
      }

In this case the response body will look like this:

      {
        "type": "http://cs.iit.edu/~virgil/cs445/mail.spring2022/project/api/problems/data-validation.html#zip_code",
        "title": "Your request data didn't pass validation",
        "detail": "The zip code may not be empty",
        "status": 400,
        "instance": "/accounts"
      }

^Top^ ^accounts^

Activate account

GET /accounts/[uid]/activate

Activates the account identified by [uid]. Returns the JSON representation of the account in the body.

HTTP response codes:

200 (OK) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not found) the account identified by [uid] doesn't exist.

Resource URL

/accounts/[uid]/activate

Parameters

None.

Example Request

      GET http://localhost:8080/bn/api/accounts/7/activate

Example Successful Response

The HTTP response code is 200 (OK).

Here's the body of the response:

        {
      		"uid": "17",
      		"name": "Joe Bloggs",
      		"address": {
      			"street": "1000 S Calhoun Ave.",
      			"zip": "60677"
      		},
      		"phone": "708-457-9012",
      		"picture": "http://example.com/images/joe-bloggs.png",
      		"is_active": true,
      		"date_created": "2022-03-13T19:01:17Z"
      	}

^Top^ ^accounts^

Update account

PUT /accounts/[uid]

Updates the account identified by [uid]. The PUT may not be used to activate the account, use instead GET /accounts/[uid]/activate

HTTP response codes:

204 (No content) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not found) the account identified by [uid] doesn't exist.

Resource URL

/accounts/[uid]

Parameters

uid (required): the id of the account performing the PUT. Technically the 'uid' is not required because it's in the URI for the request, however it is included here because it simplifies the conversion between JSON to object and object to JSON for the developer.

name (required): full name of the account holder.

address (required): a JSON representation of account holder's address.

phone (required): mobile phone number.

picture (required): for simplicity we'll just use a URL here.

is_active (required): account's status, true if active, false otherwise.

date_created (required): empty value because it's more readable; could be any value really because the PUT may not alter the value that was assigned by the original POST request.

Example Request

    PUT http://localhost:8080/bn/api/accounts/7

Here is data being PUT:

    {
      "uid": "7",
      "name": "John Smith",
      "address": {
        "street": "123 Main ST",
        "zip": "60616"
      },
      "phone": "312-456-7890",
      "picture": "http://example.com/images/john-smith.jpeg",
      "is_active": true,
      "date_created": ""
    }

Example Successful Response

The body of the response is empty. The HTTP response code is 204 (No content).

Example Response when Something Went Wrong

Let's assume that the following data is being PUT at the same URI.

    {
      "uid": "8",
      "name": "John Smith",
      "address": {
        "street": "123 Main ST",
        "zip": "60616"
      },
      "phone": "312-456-7890",
      "picture": "http://example.com/images/john-smith.jpeg",
      "is_active": true,
      "date_created": ""
    }

In this case the response body will look like this:

    {
      "type": "http://cs.iit.edu/~virgil/cs445/mail.spring2022/project/api/problems/data-validation",
      "title": "Your request data didn't pass validation",
      "detail": "This account (8) is not allowed to modify account (7)",
      "status": 400,
      "instance": "/accounts/7"
    }

^Top^ ^accounts^

View all accounts

GET /accounts

Returns a JSON array with all accounts.

HTTP response codes:

200 (OK).

Resource URL

/accounts

Parameters

None

Example Request

      GET http://localhost:8080/bn/api/accounts

Example Successful Response

      [{
      		"uid": "7",
      		"name": "John Smith",
      		"address": {
      			"street": "123 Main ST",
      			"zip": "60616"
      		},
      		"phone": "312-456-7890",
      		"picture": "http://example.com/images/john-smith.jpeg",
      		"is_active": true,
      		"date_created": "2022-03-12T17:12:26Z"
      	},
      	{
      		"uid": "11",
      		"name": "Jane Smith",
      		"address": {
      			"street": "123 2nd ST",
      			"zip": "60607"
      		},
      		"phone": "217-456-7890",
      		"picture": "http://example.com/images/jane-smith.jpeg",
      		"is_active": false,
      		"date_created": "2022-03-13T17:56:13Z"
      	},
        {
      		"uid": "17",
      		"name": "Joe Bloggs",
      		"address": {
      			"street": "1000 S Calhoun Ave.",
      			"zip": "60677"
      		},
      		"phone": "708-457-9012",
      		"picture": "http://example.com/images/joe-bloggs.png",
      		"is_active": true,
      		"date_created": "2022-03-13T19:01:17Z"
      	}
      ]

^Top^ ^accounts^

Search accounts

GET /accounts?key=keyword{&start_date=DD-MMM-YYYY&end_date=DD-MMM-YYYY}

Returns an array of accounts that match the keyword between the optionally provided start_date and end_date.

HTTP response codes:

200 (OK).

Resource URL

/accounts

Parameters

key (required): any account that has a first or last name, an address, or phone number that matches "keyword" (the value of "key") will be included in the result set. The search is case insensitive. If "keyword" is empty, then match everything.

start_date, end_date (optional): dates in the 'dd-mm-yyyy' format. 'Between' the start_date and end_date means the date_created of the resource is >= the begining of start_date and less than the end of end_date.

Example Request #1

      GET http://localhost:8080/bn/api/accounts?key=smith

Example Response

      [{
      		"uid": "7",
      		"name": "John Smith",
      		"address": {
      			"street": "123 Main ST",
      			"zip": "60616"
      		},
      		"phone": "312-456-7890",
      		"picture": "http://example.com/images/john-smith.jpeg",
      		"is_active": true,
      		"date_created": "2022-03-12T17:12:26Z"
      	},
      	{
      		"uid": "11",
      		"name": "Jane Smith",
      		"address": {
      			"street": "123 2nd ST",
      			"zip": "60607"
      		},
      		"phone": "217-456-7890",
      		"picture": "http://example.com/images/jane-smith.jpeg",
      		"is_active": false,
      		"date_created": "2022-03-13T17:56:13Z"
      	}
      ]

Example Request #2

      GET http://localhost:8080/sar/accounts?key=yellowstone

Example Response

[]

Example Request #3

      GET http://localhost:8080/bn/api/accounts?key=smith&start_date=03-12-2022&end_date=03-12-2022

Example Response

      [{
      		"uid": "7",
      		"name": "John Smith",
      		"address": {
      			"street": "123 Main ST",
      			"zip": "60616"
      		},
      		"phone": "312-456-7890",
      		"picture": "http://example.com/images/john-smith.jpeg",
      		"is_active": true,
      		"date_created": "2022-03-12T17:12:26Z"
      	}
      ]

^Top^ ^accounts^

Create ask

POST /accounts/[uid]/asks

Creates an ask by the account identified with [uid] and returns, in the header of the response, a 'Location' that points to the resource, i.e. /accounts/[uid]/asks/[aid] where [aid] is the newly assigned ID for the ask.

HTTP response code:

201 (Created) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not found) if 'uid' doesn't exist.

Resource URL

/accounts/[uid]/asks

Parameters

uid (required): the id of the account creating the ask. Technically the 'uid' is not required, however it makes JSON to object coversion a lot simpler.

aid (required): empty. The POST request will assign an immutable value for aid. Just like with uid, technically the 'aid' is not required, however it's included for simplicity as it makes JSON to object coversion a lot simpler.

type (required): Possible values are "gift", e.g. a desk, "borrow", e.g. a tool, and "help", e.g. assemble some Ikea furniture.

description (required): a description of what's being asked for.

start_date (required): a date in the 'yyyy-mm-dd' format; this could be useful when borrowing and needing help. The value may be empty.

end_date (required): a date in the 'yyyy-mm-dd' format; this could be useful when borrowing and needing help. The value may be empty.

extra_zip (required): an array of extra zip codes where the ask will be visible; the zip code of the account creating the ask is implicitly included in the visibility area.

is_active (required): ask's status, an ask will be created with a value of 'true'. An ask can be deactivated by making the value 'false' (see GET /accounts/[uid]/asks/[aid]/deactivate )

Example Request

      POST http://localhost:8080/bn/api/accounts/7/asks

Here is data being POST-ed

      {
      	"uid": "7",
        "aid": "",
      	"type": "gift",
        "description": "I need a twin bed frame with a spring box.",
        "start_date": "2022-03-14",
        "end_date": "",
        "extra_zip": ["60607", "60608"],
      	"is_active": true,
        "date_created": ""
      }

Example Response

      {
      	"uid": "7",
        "aid": "23",
      	"type": "gift",
        "description": "I need a twin bed frame with a spring box.",
        "start_date": "2022-03-14",
        "end_date": "",
        "extra_zip": ["60607", "60608"],
      	"is_active": true,
        "date_created": "2022-03-13T13:21:23Z"
      }

Example Response when Something Went Wrong

Let's assume that the following data is being POST-ed

      {
      	"uid": "7",
        "aid": "",
      	"type": "gift",
        "description": "",
        "start_date": "2022-03-14",
        "end_date": "",
        "extra_zip": ["60607", "60608"],
      	"is_active": true,
        "date_created": ""
      }

In this case the response body will look like this:

      {
        "type": "http://cs.iit.edu/~virgil/cs445/mail.spring2022/project/api/problems/data-validation.html#asks",
        "title": "Your request data didn't pass validation",
        "detail": "The ask description may not be empty",
        "status": 400,
        "instance": "/accounts/7/asks"
      }

^Top^ ^asks^

Update ask

PUT /accounts/[uid]/asks/[aid]

Updates the ask identified by [aid] and created by account [uid]. Only active asks may be updated.

HTTP response code:

204 (No content) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not found) if the account identified by [uid] doesn't exist, or the ask identified by [aid] doesn't exist.

Resource URL

/accounts/[uid]/asks/[aid]

Parameters

uid (required): the id of the account creating the ask. Technically the 'uid' is not required, however it makes JSON to object coversion a lot simpler.

aid (required): the id of the ask that's being updated.

type (required): Possible values are "gift", "borrow", and "help".

description (required): a description of what's being asked for.

start_date (required): a date in the 'yyyy-mm-dd' format; this could be useful when borrowing and needing help. The value may be empty.

end_date (required): a date in the 'yyyy-mm-dd' format; this could be useful when borrowing and needing help. The value may be empty.

extra_zip (required): an array of extra zip codes where the ask will be visible; the zip code of the account creating the ask is implicitly included in the visibility area.

is_active: must be 'true' since only active asks may be updated.

date_created (required): the value originally returned by the POST request that created the ask; regardless, this value is immutable.

Example Request

      PUT http://localhost:8080/bn/api/accounts/7/asks/23

Here is data being PUT:

      {
        "uid": "7",
        "aid": "23",
        "type": "gift",
        "description": "I need a twin bed frame with a spring box. I'll pick up.",
        "start_date": "2022-03-14",
        "end_date": "",
        "extra_zip": ["60605", "60607", "60608"],
        "is_active": true,
        "date_created": "2022-03-13T13:21:23Z"
      }

Example Successful Response

The body of the response is empty. The HTTP response code is 204 (No content).

Example Response when Something Went Wrong

Let's assume that the following data is being PUT at /accounts/11/asks/30

      {
        "uid": "11",
        "aid": "30",
        "type": "borrow",
        "description": "I need a cordless drill for a few hours on 3/16; I have the bits",
        "start_date": "2022-03-16",
        "end_date": "2022-03-16",
        "extra_zip": ["60607", "60608"],
        "is_active": true,
        "date_created": "2022-03-14T14:39:07Z"
      }

In this case the response body will look like this:

      {
        "type": "http://cs.iit.edu/~virgil/cs445/mail.spring2022/project/api/problems/data-validation.html#asks",
        "title": "Your request data didn't pass validation",
        "detail": "This account (11) didnot create ask (30) and is not allowed to update it",
        "status": 400,
        "instance": "/accounts/11/asks/30"
      }

^Top^ ^asks^

Delete ask

DELETE /accounts/[uid]/asks/[aid]

Deletes the ask identified by [aid] and all subordinated resources, i.e. notes.

NOTE: as noted somewhere else in the document deleting resources can be very difficult, in particular when there are subordinated resources and resources referencing the resource being deleted or the subordinated resources.

HTTP response codes:

204 (No content) if the ask and its subordinated resources have been removed and there is no additional information in the body of the response.
404 (Not found) if the account identified by [uid], or the ask identified by [aid] doesn't exist.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.

Resource URL

/accounts/[uid]/asks/[aid]

Parameters

None

Example Request

    DELETE http://localhost:8080/bn/api/accounts/11/asks/29

Example Successful Response

The body of the response is empty. The HTTP response code is 204 (No Content)

^Top^ ^asks^

View my asks

GET /accounts/[uid]/asks{?is_active=[true|false]}

Returns an array with all asks created by account [uid].

HTTP response codes:

200 (OK).
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not found) if 'uid' doesn't exist.

Resource URL

/accounts/[uid]/asks

Parameters

active (optional): may only have two values, 'true' and 'false', to indicate what asks are being returned. If this paarameter is missing all asks will be returned, both active and inactive.

Example Request

      GET http://localhost:8080/bn/api/accounts/7/asks

Example Successful Response

      [{
      		"uid": "7",
      		"aid": "23",
      		"type": "gift",
      		"description": "I need a twin bed frame with a spring box.",
      		"start_date": "2022-03-14",
      		"end_date": "",
      		"extra_zip": ["60607", "60608"],
      		"is_active": false,
      		"date_created": "2022-03-13T13:21:23Z"
      	},
      	{
      		"uid": "7",
      		"aid": "31",
      		"type": "help",
      		"description": "I need help assembling an IKEA desk, I don't have any tools",
      		"start_date": "2022-03-17",
      		"end_date": "",
      		"extra_zip": [],
      		"is_active": true,
      		"date_created": "2022-03-14T15:16:17Z"
      	}
      ]

Amother Example Request

      GET http://localhost:8080/bn/api/accounts/7/asks?active=true

Example Successful Response

      [{
          "uid": "7",
          "aid": "31",
          "type": "help",
          "description": "I need help assembling an IKEA desk, I don't have any tools",
          "start_date": "2022-03-17",
          "end_date": "",
          "extra_zip": [],
          "is_active": true,
          "date_created": "2022-03-14T15:16:17Z"
        }
      ]

^Top^ ^asks^

View all asks

GET /asks?v_by=viewed_by_id&is_active=[true|false]

Returns an array with all asks visible to the account making the request, as specified by the value of 'v_by'.

HTTP response codes:

200 (OK).

Resource URL

/asks

Parameters

v_by (required): the ID of the account making the request; if it's for an RU account, then return all the asks visible for the account. If the ID represent a CSR account, then return all asks.

is_active (required): if empty then return all accounts regardles of status; otherwise, if a value is specified -- 'true' or 'false' only -- then return asks with the specified status.

Example Request #1

    GET http://localhost:8080/bn/api/asks

This request should fail with a 400 (Bad Request) HTTP status because the URI has no query string.

Example Response

   {
     "type": "http://cs.iit.edu/~virgil/cs445/mail.spring2022/project/api/problems/data-validation.html#asks",
     "title": "Your request data didn't pass validation",
     "detail": "Missing query string, please consult the API documentation",
     "status": 400,
     "instance": "/asks"
   }

Example Request #2

     GET http://localhost:8080/bn/api/asks?v_by=7&is_active=

This request should all asks visible to account with uid=7, whether active or not.

Example Successful Response

     [{
         "uid": "7",
         "aid": "23",
         "type": "gift",
         "description": "I need a twin bed frame with a spring box.",
         "start_date": "2022-03-14",
         "end_date": "",
         "extra_zip": ["60607", "60608"],
         "is_active": false,
         "date_created": "2022-03-13T13:21:23Z"
       },
       {
         "uid": "7",
         "aid": "31",
         "type": "help",
         "description": "I need help assembling an IKEA desk, I don't have any tools",
         "start_date": "2022-03-17",
         "end_date": "",
         "extra_zip": [],
         "is_active": true,
         "date_created": "2022-03-14T15:16:17Z"
       },
       {
         "uid": "11",
         "aid": "29",
         "type": "borrow",
         "description": "I need a cordless drill for a few hours on 3/16; I have the bits",
         "start_date": "2022-03-16",
         "end_date": "2022-03-16",
         "extra_zip": ["60616", "60608"],
         "is_active": true,
         "date_created": "2022-03-14T14:39:07Z"
       }
     ]

Example Request #3

    GET http://localhost:8080/bn/api/asks?v_by=7&is_active=true

This request should all active asks visible to account with uid=7.

Example Successful Response

    [{
    		"uid": "7",
    		"aid": "31",
    		"type": "help",
    		"description": "I need help assembling an IKEA desk, I don't have any tools",
    		"start_date": "2022-03-17",
    		"end_date": "",
    		"extra_zip": [],
    		"is_active": true,
    		"date_created": "2022-03-14T15:16:17Z"
    	},
    	{
    		"uid": "11",
    		"aid": "29",
    		"type": "borrow",
    		"description": "I need a cordless drill for a few hours on 3/16; I have the bits",
    		"start_date": "2022-03-16",
    		"end_date": "2022-03-16",
    		"extra_zip": ["60616", "60608"],
    		"is_active": true,
    		"date_created": "2022-03-14T14:39:07Z"
    	}
    ]

Example Request #4

    GET http://localhost:8080/bn/api/asks?v_by=0&is_active=

Assuming that the account with uid=0 is a CSR account, this request should return all asks, whether active or not. Otherwise it should return a 400 (Bad Request) HTTP status.

Example Successful Response

    [{
        "uid": "7",
        "aid": "23",
        "type": "gift",
        "description": "I need a twin bed frame with a spring box.",
        "start_date": "2022-03-14",
        "end_date": "",
        "extra_zip": ["60607", "60608"],
        "is_active": false,
        "date_created": "2022-03-13T13:21:23Z"
      },
      {
        "uid": "7",
        "aid": "31",
        "type": "help",
        "description": "I need help assembling an IKEA desk, I don't have any tools",
        "start_date": "2022-03-17",
        "end_date": "",
        "extra_zip": [],
        "is_active": true,
        "date_created": "2022-03-14T15:16:17Z"
      },
      {
        "uid": "11",
        "aid": "29",
        "type": "borrow",
        "description": "I need a cordless drill for a few hours on 3/16; I have the bits",
        "start_date": "2022-03-16",
        "end_date": "2022-03-16",
        "extra_zip": ["60616", "60608"],
        "is_active": true,
        "date_created": "2022-03-14T14:39:07Z"
      },
      {
        "uid": "17",
        "aid": "37",
        "type": "gift",
        "description": "I need a couple of moving boxes",
        "start_date": "2022-03-15",
        "end_date": "",
        "extra_zip": [],
        "is_active": true,
        "date_created": "2022-03-14T16:16:16Z"
      }
    ]

^Top^ ^asks^

Search asks

GET /asks?key=keyword{&start_date=DD-MMM-YYYY&end_date=DD-MMM-YYYY}

Returns an array of asks that match the keyword and have been created between the optionally provided start_date and end_date.

HTTP response codes:

200 (OK).

Resource URL

/asks

Parameters

key (required): any ask that has a type, description, extra_zip, or has been created by an account that has a first or last name, an address, or phone number that matches "keyword" (the value of "key") will be included in the result set. The search is case insensitive. If "keyword" is empty, then match everything.

Example Request #1

      GET http://localhost:8080/bn/api/asks?key=box

Example Response

      [{
          "uid": "7",
          "aid": "23",
          "type": "gift",
          "description": "I need a twin bed frame with a spring box.",
          "start_date": "2022-03-14",
          "end_date": "",
          "extra_zip": ["60607", "60608"],
          "is_active": false,
          "date_created": "2022-03-13T13:21:23Z"
        },
        {
          "uid": "17",
          "aid": "37",
          "type": "gift",
          "description": "I need a couple of moving boxes",
          "start_date": "2022-03-15",
          "end_date": "",
          "extra_zip": [],
          "is_active": true,
          "date_created": "2022-03-14T16:16:16Z"
        }
      ]

Example Request #1

      GET http://localhost:8080/bn/api/asks?key=box&start_date=13-03-2022&end_date=13-03-2022

Example Response

      [{
          "uid": "7",
          "aid": "23",
          "type": "gift",
          "description": "I need a twin bed frame with a spring box.",
          "start_date": "2022-03-14",
          "end_date": "",
          "extra_zip": ["60607", "60608"],
          "is_active": false,
          "date_created": "2022-03-13T13:21:23Z"
        }
      ]

^Top^ ^asks^

Create give

POST /accounts/[uid]/gives

Creates a give by the account identified with [uid] and returns, in the header of the response, a 'Location' that points to the resource, i.e. /accounts/[uid]/gives/[gid] where [gid] is the newly assigned ID for the give.

HTTP response code:

201 (Created) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not found) if 'uid' doesn't exist.

Resource URL

/accounts/[uid]/gives

Parameters

uid (required): the id of the account creating the ask. Technically the 'uid' is not required, however it makes JSON to object coversion a lot simpler.

gid (required): empty. The POST request will assign an immutable value for gid. Just like with uid, technically the 'gid' is not required, however it's included for simplicity as it makes JSON to object coversion a lot simpler.

type (required): Possible values are "gift", e.g. a desk or book, "service", e.g. a haircut, "lend", e.g. a wheelbarrow, and "share", e.g. a cake or a keg of beer.

description (required): a description of what's being given.

start_date (required): a date in the 'yyyy-mm-dd' format; the value may be empty.

end_date (required): a date in the 'yyyy-mm-dd' format; the value may be empty.

extra_zip (required): an array of extra zip codes where the give will be visible; the zip code of the account creating the give is implicitly included in the visibility area.

is_active (required): give's status, a give will be created with a value of 'true'. A give can be deactivated by making the value 'false' (see GET /accounts/[uid]/gives/[gid]/deactivate )

Example Request

      POST http://localhost:8080/bn/api/accounts/7/gives

Here is data being POST-ed

      {
      	"uid": "7",
        "gid": "",
      	"type": "gift",
        "description": "Are you interested in a wireless router in working condition?",
        "start_date": "2022-03-15",
        "end_date": "",
        "extra_zip": ["60607", "60608"],
      	"is_active": true,
        "date_created": ""
      }

Example Response

      {
      	"uid": "7",
        "gid": "41",
      	"type": "gift",
        "description": "Are you interested in a wireless router in working condition?",
        "start_date": "2022-03-15",
        "end_date": "",
        "extra_zip": ["60607", "60608"],
      	"is_active": true,
        "date_created": "2022-03-15T10:41:41Z"
      }

Example Response when Something Went Wrong

Let's assume that the following data is being POST-ed

      {
      	"uid": "7",
        "gid": "",
      	"type": "gift",
        "description": "",
        "start_date": "2022-03-15",
        "end_date": "",
        "extra_zip": ["60607", "60608"],
      	"is_active": true,
        "date_created": ""
      }

In this case the response body will look like this:

      {
        "type": "http://cs.iit.edu/~virgil/cs445/mail.spring2022/project/api/problems/data-validation.html#gives",
        "title": "Your request data didn't pass validation",
        "detail": "The give description may not be empty",
        "status": 400,
        "instance": "/accounts/7/gives"
      }

^Top^ ^gives^

Update give

PUT /accounts/[uid]/gives/[gid]

Updates the give identified by [gid] and created by account [uid]. Only active gives may be updated.

HTTP response code:

204 (No content) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not found) if the account identified by [uid] doesn't exist, or the ask identified by [aid] doesn't exist.

Resource URL

/accounts/[uid]/gives/[gid]

Parameters

uid (required): the id of the account creating the ask. Technically the 'uid' is not required, however it makes JSON to object coversion a lot simpler.

gid (required): the id of the ask that's being updated.

type (required): possible values are "gift", "service", "lend", and "share".

description (required): a description of what's being given.

start_date (required): a date in the 'yyyy-mm-dd' format; the value may be empty.

end_date (required): a date in the 'yyyy-mm-dd' format; the value may be empty.

extra_zip (required): an array of extra zip codes where the give will be visible; the zip code of the account creating the give is implicitly included in the visibility area.

is_active: must be 'true' since only active gives may be updated.

date_created (required): the value originally returned by the POST request that created the give; regardless, this value is immutable.

Example Request

      PUT http://localhost:8080/bn/api/accounts/19/gives/43

Here is data being PUT:

      {
        "uid": "19",
        "gid": "43",
        "type": "service",
        "description": "One free braiding every Monday morning, first to request wins.",
        "start_date": "2022-03-21",
        "end_date": "",
        "extra_zip": ["60605", "60607", "60608", "60616"],
        "is_active": true,
        "date_created": "2022-03-13T13:21:23Z"
      }

Example Successful Response

The body of the response is empty. The HTTP response code is 204 (No content).

Example Response when Something Went Wrong

Let's assume that the following data is being PUT at /accounts/7/gives/41

      {
        "uid": "7",
        "gid": "41",
        "type": "gift",
        "description": "Are you interested in a wireless router in working condition?",
        "start_date": "2022-03-15",
        "end_date": "",
        "extra_zip": ["60607", "60608"],
        "is_active": false,
        "date_created": "2022-03-15T10:41:41Z"
      }

In this case the response body will look like this:

      {
        "type": "http://cs.iit.edu/~virgil/cs445/mail.spring2022/project/api/problems/data-validation.html#gives",
        "title": "Your request data didn't pass validation",
        "detail": "You may not update an inactive give.",
        "status": 400,
        "instance": "/accounts/7/gives/41"
      }

^Top^ ^gives^

Delete give

DELETE /accounts/[uid]/gives/[gid]

Deletes the give identified by [gid] and all subordinated resources, i.e. notes.

HTTP response codes:

204 (No content) if the give has been removed and there is no additional information in the body of the response.
404 (Not found) if the account identified by [uid], or the give identified by [gid] doesn't exist.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.

Resource URL

/accounts/[uid]/gives/[gid]

Parameters

None

Example Request

    DELETE http://localhost:8080/bn/api/accounts/19/gives/43

Example Successful Response

The body of the response is empty. The HTTP response code is 204 (No Content)

^Top^ ^gives^

View my gives

GET /accounts/[uid]/gives{?is_active=[true|false]}

Returns an array with all gives created by account [uid].

HTTP response codes:

200 (OK).
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not found) if 'uid' doesn't exist.

Resource URL

/accounts/[uid]/gives

Parameters

active (optional): may only have two values, 'true' and 'false', to indicate what asks are being returned. If this parameter is missing all asks will be returned, both active and inactive.

Example Request

      GET http://localhost:8080/bn/api/accounts/7/gives

Example Successful Response

      [{
      		"uid": "7",
      		"gid": "41",
      		"type": "gift",
      		"description": "Are you interested in a wireless router in working condition?",
      		"start_date": "2022-03-15",
      		"end_date": "",
      		"extra_zip": ["60607", "60608"],
      		"is_active": false,
      		"date_created": "2022-03-15T10:41:41Z"
      	},
      	{
      		"uid": "7",
      		"gid": "47",
      		"type": "share",
      		"description": "St. Patrick's beer party on my lawn, starts at 5pm on Thursday!",
      		"start_date": "2022-03-17",
      		"end_date": "2022-03-17",
      		"extra_zip": [],
      		"is_active": true,
      		"date_created": "2022-03-15T21:28:47Z"
      	}
      ]

Another Example Request

      GET http://localhost:8080/bn/api/accounts/7/gives?active=false

Example Successful Response

      [{
      		"uid": "7",
      		"gid": "41",
      		"type": "gift",
      		"description": "Are you interested in a wireless router in working condition?",
      		"start_date": "2022-03-15",
      		"end_date": "",
      		"extra_zip": ["60607", "60608"],
      		"is_active": false,
      		"date_created": "2022-03-15T10:41:41Z"
      	}
      ]

^Top^ ^gives^

View all gives

GET /gives?v_by=viewed_by_id&is_active=[true|false]

Returns an array with all gives visible to the account making the request as specified by the value of 'v_by'.

HTTP response codes:

200 (OK).

Resource URL

/gives

Parameters

v_by (required): the ID of the account making the request; if it's for a RU account, then return all the gives visible for the account. If the ID represents a CSR account, then return all gives.

is_active (required): if empty then return all accounts regardles of status; otherwise, if a value is specified -- 'true' or 'false' only -- then return gives with the specified status.

Example Request #1

    GET http://localhost:8080/bn/api/gives?v_by=7&is_active=

This request should return all gives visible to account with uid=7, whether active or not.

Example Successful Response

    [{
        "uid": "7",
        "gid": "41",
        "type": "gift",
        "description": "Are you interested in a wireless router in working condition?",
        "start_date": "2022-03-15",
        "end_date": "",
        "extra_zip": ["60607", "60608"],
        "is_active": false,
        "date_created": "2022-03-15T10:41:41Z"
      },
      {
        "uid": "7",
        "gid": "47",
        "type": "share",
        "description": "St. Patrick's beer party on my lawn, starts at 5pm on Thursday!",
        "start_date": "2022-03-17",
        "end_date": "2022-03-17",
        "extra_zip": [],
        "is_active": true,
        "date_created": "2022-03-15T21:28:47Z"
      },
      {
        "uid": "11",
        "gid": "53",
        "type": "lend",
        "description": "Need a snowblower? You can have mine for an hour, gas provided.",
        "start_date": "2022-03-15",
        "end_date": "",
        "extra_zip": ["60616"],
        "is_active": true,
        "date_created": "2022-03-15T21:53:53Z"
      },
      {
        "uid": "19",
        "gid": "43",
        "type": "service",
        "description": "One free braiding every Monday morning, first to request wins.",
        "start_date": "2022-03-21",
        "end_date": "",
        "extra_zip": ["60605", "60607", "60608", "60616"],
        "is_active": true,
        "date_created": "2022-03-13T13:21:23Z"
      }
    ]

Example Request #2

    GET http://localhost:8080/bn/api/gives?v_by=7&is_active=true

This request should all active gives visible to account with uid=7.

Example Successful Response

    [{
        "uid": "7",
        "gid": "47",
        "type": "share",
        "description": "St. Patrick's beer party on my lawn, starts at 5pm on Thursday!",
        "start_date": "2022-03-17",
        "end_date": "2022-03-17",
        "extra_zip": [],
        "is_active": true,
        "date_created": "2022-03-15T21:28:47Z"
      },
      {
        "uid": "11",
        "gid": "53",
        "type": "lend",
        "description": "Need a snowblower? You can have mine for an hour, gas provided.",
        "start_date": "2022-03-15",
        "end_date": "",
        "extra_zip": ["60616"],
        "is_active": true,
        "date_created": "2022-03-15T21:53:53Z"
      },
      {
        "uid": "19",
        "gid": "43",
        "type": "service",
        "description": "One free braiding every Monday morning, first to request wins.",
        "start_date": "2022-03-21",
        "end_date": "",
        "extra_zip": ["60605", "60607", "60608", "60616"],
        "is_active": true,
        "date_created": "2022-03-13T13:21:23Z"
      }
    ]

Example Request #3

    GET http://localhost:8080/bn/api/gives?v_by=&is_active=

This request should return a 400 (Bad Request) HTTP status because a value for 'v_by' is missing.

Example Response

    {
    	"type": "http://cs.iit.edu/~virgil/cs445/mail.spring2022/project/api/problems/data-validation.html#gives",
    	"title": "Your request data didn't pass validation",
    	"detail": "v_by must have a value",
    	"status": 400,
    	"instance": "/gives"
    }

^Top^ ^gives^

Search gives

GET /gives?key=keyword{&start_date=DD-MMM-YYYY&end_date=DD-MMM-YYYY}

Returns an array of gives that match the keyword and have been created between the optionally provided start_date and end_date.

HTTP response codes:

200 (OK).

Resource URL

/gives

Parameters

key (required): any give that has a type, description, extra_zip, or has been created by an account that has a first or last name, an address, or phone number that matches "keyword" (the value of "key") will be included in the result set. The search is case insensitive. If "keyword" is empty, then match everything.

Example Request #1

      GET http://localhost:8080/bn/api/gives?key=share

Example Response

      [{
        "uid": "7",
        "gid": "47",
        "type": "share",
        "description": "St. Patrick's beer party on my lawn, starts at 5pm on Thursday!",
        "start_date": "2022-03-17",
        "end_date": "2022-03-17",
        "extra_zip": [],
        "is_active": true,
        "date_created": "2022-03-15T21:28:47Z"
      }]

^Top^ ^gives^

Create thank

POST /accounts/[uid]/thanks

Creates a thank by the account identified with [uid] and returns, in the header of the response, a 'Location' that points to the resource, i.e. /accounts/[uid]/thanks/[tid] where [tid] is the newly assigned ID for the thank.

HTTP response code:

201 (Created) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not found) if 'uid' doesn't exist.

Resource URL

/accounts/[uid]/thanks

Parameters

uid (required): the id of the account creating the thank. Technically the 'uid' is not required, however it makes JSON to object coversion a lot simpler.

tid (required): empty. The POST request will assign an immutable value for tid.

thank_to (required): the ID of the account the thank is for.

description (required): a description of what the thank is for.

date_created (required): empty value. The POST will create the resource and assign a value to 'date_created'. Once populated the value of "date_created" cannot be changed.

Example Request

      POST http://localhost:8080/bn/api/accounts/61/thanks

Here is data being POST-ed

      {
      	"uid": "61",
        "tid": "",
      	"thank_to": "7",
        "description": "The beer party yesterday was fantastic, thank you for sharing the keg!",
        "date_created": "2022-03-18T11:12:13Z"
      }

Example Response

      {
      	"uid": "61",
        "tid": "67",
      	"thank_to": "7",
        "description": "The beer party yesterday was fantastic, thank you for sharing the keg!",
        "date_created": "2022-03-18T11:12:13Z"
      }

^Top^ ^thanks^

Update thank

PUT /accounts/[uid]/thanks/[tid]

Updates the thank identified by [tid] and created by account [uid].

HTTP response code:

204 (No content) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not found) if the account identified by [uid] doesn't exist, or the ask identified by [aid] doesn't exist.

Resource URL

/accounts/[uid]/thanks/[tid]

Parameters

uid (required): the id of the account updating the thank, must be the same as the creator of it.

tid (required): the ID of this thank.

thank_to (required): the ID of the account the thank is for.

description (required): a description of what the thank is for.

date_created (required): the value originally returned by the POST request that created the thank; regardless, this value is immutable.

Example Request

      PUT http://localhost:8080/bn/api/accounts/71/thanks/73

Here is data being PUT:

      {
      	"uid": "71",
        "tid": "73",
      	"thank_to": "19",
        "description": "Alice, thank you so much, I love my new braids.",
        "date_created": "2022-03-21T11:45:19Z"
      }

Example Successful Response

The body of the response is empty. The HTTP response code is 204 (No content).

^Top^ ^thanks^

Search thanks

GET /thanks?key=keyword{&start_date=DD-MMM-YYYY&end_date=DD-MMM-YYYY}

Returns an array of thanks that match the keyword and have been created between the optionally provided start_date and end_date.

HTTP response codes:

200 (OK).

Resource URL

/thanks

Parameters

key (required): any thank that has a description, or has been created by, or is addressed to an account that has a first or last name, an address, or phone number that matches "keyword", (the value of "key") will be included in the result set. The search is case insensitive. If "keyword" is empty, then match everything.

Example Request #1

      GET http://localhost:8080/bn/api/gives?key=beer

Example Response

      [{
          "uid": "61",
          "tid": "67",
          "thank_to": "7",
          "description": "The beer party yesterday was fantastic, thank you for sharing the keg!",
          "date_created": "2022-03-18T11:12:13Z"
        }]

^Top^ ^thanks^

Create note

POST /notes

Creates a note: a note is in response to an ask, a give, or an existing note. A note can be the beginning of a converation thread between the account that created the original ask or give -- we'll call it the creator -- and the responder, the account that has an interest in the original post. The POST request returns, in the header of the response, a 'Location' that points to the resource, i.e. /notes/[nid] where [nid] is the newly assigned ID for the note.

HTTP response code:

201 (Created) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.

Resource URL

/notes

Parameters

uid (required): the id of the account creating the note.

nid (required): empty. The POST request will assign an immutable value for nid, the note id.

to_type (required): the type of resource the note is for, either "ask", "give", or "note".

to_user_id (required): the id of the account the note is for.

to_id (required): the id of the resource the note is for, either an [aid], a [gid], or an [nid].

description (required): the content of the note.

date_created (required): empty value. The POST will create the resource and assign a value to 'date_created'. Once populated the value of "date_created" cannot be changed.

Example Request #1

      POST http://localhost:8080/bn/api/notes

This note is created by the account identified by uid=71, to express interest in the "give" identified by to_id=43 that was created by the account identified with to_user_id=19.

Here is data being POST-ed

      {
      	"uid": "71",
        "nid": "",
        "to_type": "give",
        "to_user_id": "19",
      	"to_id": "43",
        "description": "Can I get braids this coming Monday?",
        "date_created": ""
      }

Example Response

      {
      	"uid": "71",
        "nid": "97",
        "to_type": "give",
        "to_user_id": "19",
      	"to_id": "43",
        "description": "Can I get braids this coming Monday?",
        "date_created": "2022-03-13T13:33:06Z"
      }

Example Request #2

      POST http://localhost:8080/bn/api/notes

Here is data being POST-ed

      {
      	"uid": "79",
        "nid": "",
        "to_type": "give",
        "to_user_id": "19",
      	"to_id": "43",
        "description": "Is this Monday's spot taken already?",
        "date_created": ""
      }

Example Response

      {
      	"uid": "79",
        "nid": "101",
        "to_type": "give",
        "to_user_id": "19",
      	"to_id": "43",
        "description": "Is this Monday's spot taken already?",
        "date_created": "2022-03-13T13:55:11Z"
      }

Example Request #3

      POST http://localhost:8080/bn/api/notes

Here is data being POST-ed

      {
        "uid": "19",
        "nid": "",
        "to_type": "note",
        "to_user_id": "71",
        "to_id": "97",
        "description": "You're the first to ask, it's yours",
        "date_created": ""
      }

Example Response

      {
        "uid": "19",
        "nid": "103",
        "to_type": "note",
        "to_user_id": "71",
        "to_id": "97",
        "description": "You're the first to ask, it's yours",
        "date_created": "2022-03-13T13:39:19Z"
      }

Example Request #4

      POST http://localhost:8080/bn/api/notes

Here is data being POST-ed

      {
        "uid": "19",
        "nid": "",
        "to_type": "note",
        "to_user_id": "79",
        "to_id": "101",
        "description": "Sorry, you're a couple minutes too late, try again next week.",
        "date_created": ""
      }

Example Response

      {
        "uid": "19",
        "nid": "107",
        "to_type": "note",
        "to_user_id": "79",
        "to_id": "101",
        "description": "Sorry, you're a couple minutes too late, try again next week.",
        "date_created": "2022-03-13T14:09:14Z"
      }

^Top^ ^notes^

Update note

PUT /notes/[nid]

Updates the note identified by [nid].

HTTP response code:

204 (No content) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not found) if the note identified by [nid] doesn't exist.

Resource URL

/notes/[nid]

Parameters

uid (required): the id of the account updating the note.

nid (required): the note id.

to_type (required): the type of resource the note is for, either "ask", "give", or "note".

to_user_id (required): the id of the account the note is for.

to_id (required): the id of the resource the note is for, either an [aid], a [gid], or an [nid].

description (required): the content of the note.

date_created (required): the value originally returned by the POST request that created the thank; regardless, this value is immutable.

Example Request

      PUT http://localhost:8080/bn/api/notes/103

Here is data being PUT:

      {
        "uid": "19",
        "nid": "103",
        "to_type": "note",
        "to_user_id": "71",
        "to_id": "97",
        "description": "You're the first to ask, it's yours next Monday at 9am.",
        "date_created": "2022-03-13T13:39:19Z"
      }

Example Successful Response

The body of the response is empty. The HTTP response code is 204 (No content).

^Top^ ^notes^

View notes

GET /notes{?c_by=created_by_id&v_by=viewed_by_id&type=[ask|give]&agid=ask_or_give_id}

If the query string is missing from the URI, then return an array of all conversations.

The effect of the query string is to narrow down the result set, as follows:

if a value is provided for 'c_by', then only return conversations related to asks/gives created by the 'created_by_id' account.
if a value is provided for 'v_by', then only show those conversations that were initiated by the account identified with 'viewed_by_id'.
if a value is provided for 'type', then only returns conversations related to an ask or a give.
if a value is provided for 'agid', then only return conversations related to that specific ID ('type' specifies if it's an "ask" or a "give").

NOTE: all elements of the query string, i.e. c_by, v_by, type, and agid must be present together or all missing.

HTTP response code:

201 (Created) if everything is ok.
400 (Bad Request) if any of the required data is missing or is invalid. In this case the body of the response should contain JSON that explains what went wrong.
404 (Not Found) if thw values for 'c_by', 'v_by', 'type', or 'agid' don't exist.

Resource URL

/notes

Parameters

c_by: the ID of the account that created the ask/give at the origin of the conversation. The value of 'c_by' may be empty.

v_by: the ID of the account that initiated the conversation in response to an ask or a give.

type: can be "ask", "give", or empty.

agid: the ID of the ask/give the conversation is in reference to.

Example Request #1

      GET http://localhost:8080/bn/api/notes

Example Response

      [{
      		"uid": "19",
      		"source_id": "43",
      		"conversations": [{
      				"with_uid": "71",
      				"notes": [{
      						"uid": "71",
      						"nid": "97",
      						"to_type": "give",
      						"to_user_id": "19",
      						"to_id": "43",
      						"description": "Can I get braids this coming Monday?",
      						"date_created": "2022-03-13T13:33:06Z"
      					},
      					{
      						"uid": "19",
      						"nid": "103",
      						"to_type": "note",
      						"to_user_id": "71",
      						"to_id": "97",
      						"description": "You're the first to ask, it's yours.",
      						"date_created": "2022-03-13T13:39:19Z"
      					}
      				]
      			},
      			{
      				"with_uid": "79",
      				"notes": [{
      						"uid": "79",
      						"nid": "101",
      						"to_type": "give",
      						"to_user_id": "19",
      						"to_id": "43",
      						"description": "Is this Monday's spot taken already?",
      						"date_created": "2022-03-13T13:55:11Z"
      					},
      					{
      						"uid": "19",
      						"nid": "107",
      						"to_type": "note",
      						"to_user_id": "79",
      						"to_id": "101",
      						"description": "Sorry, you're a couple minutes too late, try again next week.",
      						"date_created": "2022-03-13T14:09:14Z"
      					}
      				]
      			}
      		]
      	},
      	{
      		"uid": "7",
      		"source_id": "31",
      		"conversations": [{
      				"with_uid": "79",
      				"notes": [{
      						"uid": "79",
      						"nid": "137",
      						"to_type": "ask",
      						"to_user_id": "7",
      						"to_id": "31",
      						"description": "IKEA is my middle name, when do you need help?",
      						"date_created": "2022-03-14T22:16:17Z"
      					},
      					{
      						"uid": "7",
      						"nid": "139",
      						"to_type": "note",
      						"to_user_id": "79",
      						"to_id": "137",
      						"description": "Thank you, how's tomorrow after 5pm?  I'm at 123 Main ST.",
      						"date_created": "2022-03-15T10:00:01Z"
      					},
      					{
      						"uid": "79",
      						"nid": "149",
      						"to_type": "note",
      						"to_user_id": "7",
      						"to_id": "139",
      						"description": "Got it, see you tomorrow around 5:30pm.",
      						"date_created": "2022-03-15T13:21:59Z"
      					}
      				]
      			},
      			{
      				"with_uid": "61",
      				"notes": [{
      						"uid": "61",
      						"nid": "127",
      						"to_type": "give",
      						"to_user_id": "7",
      						"to_id": "41",
      						"description": "I could use that wireless router, do you have setup instructions?",
      						"date_created": "2022-03-17T18:31:37Z"
      					},
      					{
      						"uid": "7",
      						"nid": "131",
      						"to_type": "note",
      						"to_user_id": "7",
      						"to_id": "127",
      						"description": "I can help you with the setup. I can drop it off and help you any day.",
      						"date_created": "2022-03-17T19:20:21Z"
      					}
      				]
      			}
      		]
      	}
      ]

Example Request #2

      GET http://localhost:8080/bn/api/notes?c_by=7&v_by=79&type=&agid=

Example Response

      [{
      	"uid": "7",
      	"source_id": "31",
      	"conversations": [{
      		"with_uid": "79",
      		"notes": [{
      				"uid": "79",
      				"nid": "137",
      				"to_type": "ask",
      				"to_user_id": "7",
      				"to_id": "31",
      				"description": "IKEA is my middle name, when do you need help?",
      				"date_created": "2022-03-14T22:16:17Z"
      			},
      			{
      				"uid": "7",
      				"nid": "139",
      				"to_type": "note",
      				"to_user_id": "79",
      				"to_id": "137",
      				"description": "Thank you, how's tomorrow after 5pm?  I'm at 123 Main ST.",
      				"date_created": "2022-03-15T10:00:01Z"
      			},
      			{
      				"uid": "79",
      				"nid": "149",
      				"to_type": "note",
      				"to_user_id": "7",
      				"to_id": "139",
      				"description": "Got it, see you tomorrow around 5:30pm.",
      				"date_created": "2022-03-15T13:21:59Z"
      			}
      		]
      	}]
      }]

Example Request #3

      GET http://localhost:8080/bn/api/notes?c_by=7&v_by=79&type=give&agid=

Example Response

[]

Example Request #4

      GET http://localhost:8080/bn/api/notes?c_by=&v_by=79&type=&agid=

Example Response

      [{
      		"uid": "19",
      		"source_id": "43",
      		"conversations": [{
      			"with_uid": "79",
      			"notes": [{
      					"uid": "79",
      					"nid": "101",
      					"to_type": "give",
      					"to_user_id": "19",
      					"to_id": "43",
      					"description": "Is this Monday's spot taken already?",
      					"date_created": "2022-03-13T13:55:11Z"
      				},
      				{
      					"uid": "19",
      					"nid": "107",
      					"to_type": "note",
      					"to_user_id": "79",
      					"to_id": "101",
      					"description": "Sorry, you're a couple minutes too late, try again next week.",
      					"date_created": "2022-03-13T14:09:14Z"
      				}
      			]
      		}]
      	},
      	{
      		"uid": "7",
      		"source_id": "31",
      		"conversations": [{
      			"with_uid": "79",
      			"notes": [{
      					"uid": "79",
      					"nid": "137",
      					"to_type": "ask",
      					"to_user_id": "7",
      					"to_id": "31",
      					"description": "IKEA is my middle name, when do you need help?",
      					"date_created": "2022-03-14T22:16:17Z"
      				},
      				{
      					"uid": "7",
      					"nid": "139",
      					"to_type": "note",
      					"to_user_id": "79",
      					"to_id": "137",
      					"description": "Thank you, how's tomorrow after 5pm?  I'm at 123 Main ST.",
      					"date_created": "2022-03-15T10:00:01Z"
      				},
      				{
      					"uid": "79",
      					"nid": "149",
      					"to_type": "note",
      					"to_user_id": "7",
      					"to_id": "139",
      					"description": "Got it, see you tomorrow around 5:30pm.",
      					"date_created": "2022-03-15T13:21:59Z"
      				}
      			]
      		}]
      	}
      ]

^Top^ ^notes^

Search notes

GET /notes?key=keyword{&start_date=DD-MMM-YYYY&end_date=DD-MMM-YYYY}

Returns an array of notes that match the keyword and have been created between the optionally provided start_date and end_date. Matching will be done on the 'description' field only and is case insensitive.

HTTP response codes:

200 (OK).

Resource URL

/notes

Parameters

key (required): any note that has a description that matches 'keyword', (the value of "key") will be included in the result set. The search is case insensitive. If "keyword" is empty, then match everything.

Example Request #1

      GET http://localhost:8080/bn/api/notes?key=setup

Example Response

      [{
    		"uid": "61",
    		"nid": "127",
    		"to_type": "give",
    		"to_user_id": "7",
    		"to_id": "41",
    		"description": "I could use that wireless router, do you have setup instructions?",
    		"date_created": "2022-03-17T18:31:37Z"
    	},
    	{
    		"uid": "7",
    		"nid": "131",
    		"to_type": "note",
    		"to_user_id": "7",
    		"to_id": "127",
    		"description": "I can help you with the setup. I can drop it off and help you any day.",
    		"date_created": "2022-03-17T19:20:21Z"
    	}
    ]

^Top^ ^notes^

Get report

GET /reports/[rid]?c_by=created_by_id&v_by=viewed_by_id&start_date=DD-MMM-YYYY&end_date=DD-MMM-YYYY

Returns the report identified by [rid] for resources created by 'c_by' and requested the user 'v_by' which must be a CSR, created between the start_date and the end_date. If values are provided for start_date and end_date, then include resources that have a create_date between start_date and end_date. If only the start_date is specified, then the end_date is now(). If only the end_date is specified, then the start_date is Linux epoch.

HTTP response codes:

200 (OK).
400 (Bad Request) if the 'viewed_by_id' is not a CSR, or otherwise the query string consists of data that doesn't make sense.
404 (Not Found) if [rid] doesn't exist, and/or 'created_by_id' doesn't exist, and/or 'viewed_by_id' doesn't exist.

Resource URL

/reports/[rid]

Parameters

c_by (required): the ID of the user that created the resources that need to be included in the result set, or was involved in communications related to thoses resources.
v_by (required): the ID of the user that's requesting the report, must be a CSR.
start_date (optional): the start date for the date range of the report.
end_date (optional): the end date for the date range of the report.

Example Request

    GET http://localhost:8080/bn/api/reports/907?c_by=&v_by=2&start_date=DD-MMM-YYYY&end_date=DD-MMM-YYYY

Example Response

The response must include all asks and gives created since the value of 'c_by' is empty and and the value of 'v_by' identifies a CSR user.

If the value of 'v_by' identifies a Regular User (RU), then the request must return a 400 (Bad Request) HTTP status.

    {
    	"rid": "907",
    	"name": "Asks/gives broken down by zip",
      "c_by": "",
    	"v_by": "2",
    	"start_date": "",
    	"end_date": "",
    	"asks": 4,
    	"gives": 5,
    	"detail": [{
    		"zip": "60607",
    		"asks": {
    			"total": 1,
    			"active": 1,
    			"inactive": 0
    		},
    		"gives": {
    			"total": 1,
    			"active": 1,
    			"inactive": 0
    		}
    	}, {
    		"zip": "60608",
    		"asks": {
    			"total": 0,
    			"active": 0,
    			"inactive": 0
    		},
    		"gives": {
    			"total": 1,
    			"active": 1,
    			"inactive": 0
    		}
    	}, {
    		"zip": "60616",
    		"asks": {
    			"total": 2,
    			"active": 2,
    			"inactive": 0
    		},
    		"gives": {
    			"total": 2,
    			"active": 1,
    			"inactive": 1
    		}
    	}, {
    		"zip": "60677",
    		"asks": {
    			"total": 1,
    			"active": 1,
    			"inactive": 0
    		},
    		"gives": {
    			"total": 1,
    			"active": 1,
    			"inactive": 0
    		}
    	}]
    }

Another Example Request

    GET http://localhost:8080/bn/api/reports/911?c_by=19&v_by=2&start_date=13-Mar-2022&end_date=13-Mar-2022

Example Response

    {
      "rid": "911",
    	"name": "Asks/gives broken down by zip",
      "c_by": "19",
    	"v_by": "2",
      "start_date": "13-Mar-2022",
      "end_date": "13-Mar-2022",
      "asks": [],
      "gives": [{
        "give": {
          "uid": "19",
          "gid": "43",
          "type": "service",
          "description": "One free braiding every Monday morning, first to request wins.",
          "start_date": "2022-03-21",
          "end_date": "",
          "extra_zip": ["60605", "60607", "60608", "60616"],
          "is_active": true,
          "date_created": "2022-03-13T13:21:23Z"
        },
        "conversations": [{
            "with_uid": "71",
            "notes": [{
                "uid": "71",
                "nid": "97",
                "to_type": "give",
                "to_user_id": "19",
                "to_id": "43",
                "description": "Can I get braids this coming Monday?",
                "date_created": "2022-03-13T13:33:06Z"
              },
              {
                "uid": "19",
                "nid": "103",
                "to_type": "note",
                "to_user_id": "19",
                "to_id": "97",
                "description": "You're the first to ask, it's yours.",
                "date_created": "2022-03-13T13:39:19Z"
              }
            ]
          },
          {
            "with_uid": "79",
            "notes": [{
                "uid": "79",
                "nid": "101",
                "to_type": "give",
                "to_user_id": "19",
                "to_id": "43",
                "description": "Is this Monday's spot taken already?",
                "date_created": "2022-03-13T13:55:11Z"
              },
              {
                "uid": "19",
                "nid": "107",
                "to_type": "note",
                "to_user_id": "79",
                "to_id": "101",
                "description": "Sorry, you're a couple minutes too late, try again next week.",
                "date_created": "2022-03-13T14:09:14Z"
              }
            ]
          }
        ]
      }]
    }

^Top^ ^reports^

This section lists all known discrepancies between the requirements and the API.

Project API

Actors

accounts

Create account

Resource URL

Parameters

Example Request

Example Response

Example Response when Something Went Wrong

Activate account

Resource URL

Parameters

Example Request

Example Successful Response

Update account

Resource URL

Parameters

Example Request

Example Successful Response

Example Response when Something Went Wrong

Delete account

Resource URL

Parameters

Example Request

Example Successful Response

View all accounts

Resource URL

Parameters

Example Request

Example Successful Response

View account

Resource URL

Parameters

Example Request

Example Successful Response

Search accounts

Resource URL

Parameters

Example Request #1

Example Response

Example Request #2

Example Response

Example Request #3

Example Response

asks

Create ask

Resource URL

Parameters

Example Request

Example Response

Example Response when Something Went Wrong

Deactivate ask

Resource URL

Parameters

Example Request

Example Successful Response

Update ask

Resource URL

Parameters

Example Request

Example Successful Response

Example Response when Something Went Wrong

Delete ask

Resource URL

Parameters

Example Request

Example Successful Response

View my asks

Resource URL

Parameters

Example Request

Example Successful Response

Amother Example Request

Example Successful Response

View all asks

Resource URL

Parameters

Example Request #1

Example Response

Example Request #2