diff --git a/docs/api/API Overview.md b/docs/api/API Overview.md deleted file mode 100644 index 6384e0d..0000000 --- a/docs/api/API Overview.md +++ /dev/null @@ -1,177 +0,0 @@ -# *(draft)* API Overview -Using Flask, Flask Restful and Flask JWT (correct?) The api works as a direct connection to the storage for the items stored by the Qcli, allowing front end calls to request parsed information via url. - -Endpoints | Use -:---: | :--- -[**/api/login**](#login) | Receives a JSON encoded username and password. Sets a Refresh token cookie and returns an access token. -[**/api/tokens/refresh**](#tokensrefresh) | Gets a new refresh token. -[**/api/data/<string:queue>/<int:number>**](#acessing-items) | Returns a JSON encoded Item. -[**/api/data/<string:queues>**](#accessing-queues) | Returns a JSON encoded Queue. -[**/api/data/get_queues**](#accessing-queue-counts) | Returns a list of queues and their item counts. - -## login - -#### **Description** -Acts as a way to authenticate users to access data parsed in the back end. - -#### **Arguments** -The api login accpets a username and an already hashed password. -```json -{ - "username": form.username, - "password": sha256(form.password) -} -``` -The api accepts the hashed password and salts and hashes it an additional time and attempts to authenticate the username and the password using *insert part of flask being used here*. - -#### **Returns** -After sucesfully authenticating the username and password, the api will return an access token to then be stored in a browser cookie on the frontend -```json -{ "access_token": access_token } -``` - -#### **Errors** - -| Error | Reason | -| ---- | ---- | -| **422** | Returns if data is not json or if the json data is not formatted correctly | -| **401** | Returns if the username and/or password is invalid | - -## tokens/refresh - -#### **Description** - -Acts as a revalidation of an already authenticated user and supplies a newly created access token. - -## Acessing Items - -#### **Description** - -Items are individual "tickets", stored in a collective queue with other items. Item numbers are unique only within each queue, meaning that to access a specific item, its queue name must also be known in addition to it's item number. `ce100`, `me23`, and `eee48` would all be specific items that can all be accessed. - -#### **Arguments** - -**/api/data/*<string:queue>*/*<int:number>*** - -Argument | Type | Description -:---- | :----: | :---- -`queue` | String | The queue an item is located in -`item` | Int | The item's distinct number within the specified queue -`headersOnly` *(Optional)* | Boolean | Specify weather to only returns the headers of an item or the whole item - -An item can be accessed directly from the url by passing the queue name and the item number. -By default, the entire contents of an item are returned, but the headers of an item, without any of the content within that item, can also be returned by passing the `headersOnly=True` argument within the url: - -`/api/data/ce/100` will default to `headersOnly=False` and return the entirety of `ce 100` - -`/api/data/ce/100?headersOnly=True` will return only the headers of `ce 100` - -#### **Returns** - -When `headersOnly=False`, the full contents of an item will be returned in a json structure with these keys: - -Key | Value -------|------ -`lastUpdated` | An ISO 8601 formatted time string showing the last time the file was updated. -`headers` | A list of dictionaries containing header keys and values. -`content` | A list of section dictionaries. -`isLocked` | A boolean showing whether or not a lockfile for the item is present. -`userEmail` | The email address of the person who this item is from. -`userName` | The real name of the person who this item is from. -`userAlias` | The Purdue career account alias of the person this item is from. -`assignedTo` | The Purdue career account alias of the person this item is assigned to -`subject` | The subject of the original message for this item. -`status` | The most recent status update for the item. -`priority` | The most recent priority for this item. -`department` | The most recent department for this item. -`dateReceived` | The date this item was created. -`jsonData` | A JSON serializable representation of the Item. - -If `headersOnly=True`, then all of the key/value pairs are returned except for the `content` key and the list of dictionaries associated with it. - -## Accessing Queues - -#### **Description** - -Additionally, the information relating to all items in a queue can be accesed by simply naming the queue in the URL. Unlike acessing a specific item, acessing a queue only returns the header information for each item to decrease the time it takes to parse the information from the stored items. - -#### **Arguments** - -Accessing a queue is similar to accessing an individual item except that multiple item dictionaries are returned within a list as opposed to just one item in a singular dictionary. - -**/api/data/*<string:queues>*** - -| Argument | Type | Description | -| ---- | :----: | :---- | -| `queue` | String | The name of a queue | -| `headersOnly` *(Optional)* | Boolean | Specify weather to only returns the headers of an item or the whole item | - -By default, acessing an entire queue will return only the header information for the items within a given queue, however, it is possible to return the entire contents of all the items within a queue by passing `headersOnly=False` within the url: - -| URL | Return Description | -| --- | --- | -| `/api/data/me` | Defaults to `headersOnly=True` and returns a list of all items in the `me` queue with only the header information included. | -| `/api/data/ce?headersOnly=False` | Returns a list of all the items in the `me` queue with the entire contents of every item included. | - -It is also possible to return multiple queues by passing more than one queue name in the url. separating each queue name with "+": - -| URL | Return Description | -| --- | --- | -| `/api/data/eee+cnit` | Defaults to `headersOnly=True` and returns a list of all the items in both the `eee` and `cnit` queues with only the header information included. | -| `/api/data/eee+cnit?headersOnly=False` | Returns a list of all the items in both the `eee` and `cnit` queues with the entire contents of every item from both queues included. | - -#### **Returns** - -Returns a list of queues, with each queue being it's own dictionary with a list of items, each item represented by a dictionary. - -**JSON output:** -```json -[ - {'name': 'queue_name', - 'items': ['list_of_item_dictionaries] - }, - - {'name': 'queue_name', - 'items': ['list_of_item_dictionaries] - } -] -``` -## Accessing Queue Counts - -#### **Description** - -This will return a dictionary of all valid queues with the number of items within each queue. - -#### **Arguments** - -This function doesn't require any arguments from the url. - -#### **Returns** - -Returns a list of dictionaries with these key value pairs: -**/api/data/get_queues** - -| Key | Type | Value | -| --- | ---- | ----- | -| `name` | string | the name of the queue | -| `number_of_items` | int | the number of items within the queue | - -**JSON output:** -```json -[ - { - 'name': 'bidc', - 'number_of_items': 5 - }, - - { - 'name': 'epics', - 'number_of_items': 6 - }, - - { - 'name': 'wang', - 'number_of_items': 13 - } -] -``` \ No newline at end of file