API Documentation

• API Documentation
  • 1. Users
    • 1.1 List all users: [GET] /v1/users/
    • 1.2 View a user: [GET] /v1/user/login
    • 1.3 View a user: [POST] /v1/user/create
    • 1.4 View a user: [DEL] /v1/user/delete/:id
  • 2. Lists
    • 2.1 List all lists for a given user: [GET] /v1/lists/
    • 2.2 View a user: [GET] /v1/list/:listId
    • 2.3 [OFFLINE] Create a list: [POST] /v1/user/:userId/list/create
    • 2.4 View a user: [DEL] /v1/user/:userId/list/:listId
  • 3. Items
    • 3.1 Add item to list: [POST] /v1/list/:listId/item/add
    • 3.2 Check off grocery item: [POST] /v1/list/:listId/item/:itemId/done
    • 3.3 Delete item from list: [POST] /v1/list/:listId/item/:itemId/
    • 3.4 Update expiration: [POST] /v1/list/:listId/item/:itemId/update
  • 4. Recipes
    • 4.1 Get all the recipes in the system: [GET] /v1/recipe[?offset=[INTEGER DEFAULT=0]&limit=[INGETER DEFAULT=300]]
    • 4.2 Get ingredients for recipe: [GET] /v1/recipe/:id/ingredients
    • 4.3 Add ingredients: [GET] /v1/recipe/:id/add
    • 4.4 Suggest recipes: [GET] /v1/recipe/suggest[?q=[INTEGER 1-100] DEFAULT 100]

1. Users

1.1 List all users: [GET] /v1/users/

Description

Gets all the users. Only accepts admin tokens.

• Authentication: [Admin, User]
  • token: User token must be the one assigned to the target user or an admin token.

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

{
    users: [
        {
            "id": [INTEGER],
            "first_name": [STRING],
            "last_name": [STRING],
            "email": [STRING],
            "username": [STRING],
            "token": [STRING],
            "updatedAt": [STRING],
            "createdAt": [STRING]
        },
    ]
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {401: 'Unauthorized'}

1.2 View a user: [GET] /v1/user/login

Description

Get the user associated with the token.

• Authentication: [User]
  • token: User token must be the one assigned to the target user or an admin token.

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

{
    "id": [INTEGER],
    "first_name": [STRING],
    "last_name": [STRING],
    "email": [STRING],
    "username": [STRING],
    "token": [STRING],
    "updatedAt": [STRING],
    "createdAt": [STRING]
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {401: 'Unauthorized'}

1.3 View a user: [POST] /v1/user/create

Description

Creates a new user.

• Authentication: []

Request:

• Body:

{
    "first_name": [STRING],
    "last_name": [STRING],
    "email": [STRING],
    "username": [STRING],
    "password": [STRING]
}

Response:

{
    "id": [INTEGER],
    "first_name": [STRING],
    "last_name": [STRING],
    "email": [STRING],
    "username": [STRING],
    "token": [STRING],
    "updatedAt": [STRING],
    "createdAt": [STRING]
}

Response Status Codes:

• Success Code: {201: 'Created'}
• Error Code: {404: 'NotFoundError', 409: 'ConflictError'}

1.4 View a user: [DEL] /v1/user/delete/:id

Description

Deletes the user with the given id.

• Authentication: [Admin, User]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

• body: {}

Response Status Codes:

• Success Code: {204: 'NoContent'}
• Error Code: {403: 'Forbidden', 404: 'NotFoundError'}

2. Lists

2.1 List all lists for a given user: [GET] /v1/lists/

Description

Get all the lists for a given user.

• Authentication: [Admin, User]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

{
    list: [
        {
            "id": [INTEGER],
            "userId": [INTEGER],
            "name": [STRING],
            "description": [STRING],
            "updatedAt": [STRING],
            "createdAt": [STRING]
        }
    ]
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {403: 'Forbidden'}

2.2 View a user: [GET] /v1/list/:listId

Description

Get specified list for a user.

• Authentication: [Admin, User]
  • token: User token must be the one assigned to the target user or an admin token.

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

{
    "id": [INTEGER],
    "userId": [INTEGER],
    "description": [STRING],
    "name": [STRING],
    "description": [STRING],
    "items": [
        {
            "id": [INTEGER],
            "name": [STRING],
            "quantity": [INTEGER],
            "price": [INTEGER],
            "expiration": [STRING],
            "createdAt": [STRING],
            "updatedAt": [STRING],
            "listId": [INTEGER]
        }
    ]
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {403: 'Forbidden', 404: 'NotFoundError'}

2.3 [OFFLINE] Create a list: [POST] /v1/user/:userId/list/create

Description

Creates a new user.

• Authentication: [Admin]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}
• Body:

{
    "name": [STRING],
    "description": [STRING]
}

Response:

{
    "id": [INTEGER],
    "name": [STRING],
    "description": [STRING],
    "updatedAt": [STRING],
    "createdAt": [STRING]
}

Response Status Codes:

• Success Code: {201: 'Created'}
• Error Code: {403: 'Forbidden', 409: 'ConflictError'}

2.4 View a user: [DEL] /v1/user/:userId/list/:listId

Description

Deletes the list with the given id.

• Authentication: [Admin, User]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}
• Params: id of the user to be deleted.

Response:

• body: {}

Response Status Codes:

• Success Code: {204: 'NoContent'}
• Error Code: {403: 'Forbidden', 404: 'NotFoundError'}

3. Items

3.1 Add item to list: [POST] /v1/list/:listId/item/add

Description

Add an item to the given list

• Authentication: [User]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

{
    "list": {
        "id": [INTEGER],
        "name": [STRING],
        "description": [STRING],
        "createdAt": [STRING],
        "updatedAt": [STRING],
        "userId": [INTEGER],
        "items": [
            {
                "id": [INTEGER],
                "name": [STRING],
                "quantity": [INTEGER],
                "price": [INTEGER],
                "expiration": [STRING],
                "createdAt": [STRING],
                "updatedAt": [STRING],
                "listId": [INTEGER]
            },
        ]
    }
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {403: 'Forbidden'}

3.2 Check off grocery item: [POST] /v1/list/:listId/item/:itemId/done

Description

Move item from the grocery list to the fridge list

• Authentication: [User]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

{
    "list": {
        "id": [INTEGER],
        "name": [STRING],
        "description": [STRING],
        "createdAt": [STRING],
        "updatedAt": [STRING],
        "userId": [INTEGER],
        "items": [
            {
                "id": [INTEGER],
                "name": [STRING],
                "quantity": [INTEGER],
                "price": [INTEGER],
                "expiration": [STRING],
                "createdAt": [STRING],
                "updatedAt": [STRING],
                "listId": [INTEGER]
            },
        ]
    }
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {403: 'Forbidden'}

3.3 Delete item from list: [DELETE] /v1/list/:listId/item/:itemId/

Description

Delete an item from a given list

• Authentication: [User]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

{
    "list": {
        "id": [INTEGER],
        "name": [STRING],
        "description": [STRING],
        "createdAt": [STRING],
        "updatedAt": [STRING],
        "userId": [INTEGER],
        "items": [
            {
                "id": [INTEGER],
                "name": [STRING],
                "quantity": [INTEGER],
                "price": [INTEGER],
                "expiration": [STRING],
                "createdAt": [STRING],
                "updatedAt": [STRING],
                "listId": [INTEGER]
            },
        ]
    }
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {403: 'Forbidden'}

3.4 Update expiration: [POST] /v1/list/:listId/item/:itemId/update

Description

Update an expiration date

• Authentication: [User]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}
• Body:

{
    "expiration": [STRING YYYY-MM-DD]
}

Response:

{
    "list": {
        "id": [INTEGER],
        "name": [STRING],
        "description": [STRING],
        "createdAt": [STRING],
        "updatedAt": [STRING],
        "userId": [INTEGER],
        "items": [
            {
                "id": [INTEGER],
                "name": [STRING],
                "quantity": [INTEGER],
                "price": [INTEGER],
                "expiration": [STRING],
                "createdAt": [STRING],
                "updatedAt": [STRING],
                "listId": [INTEGER]
            },
        ]
    }
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {403: 'Forbidden'}

4. Recipes

4.1 Get all the recipes in the system: [GET] /v1/recipe[?offset=[INTEGER DEFAULT=0]&limit=[INGETER DEFAULT=300]]

Description

• Offset n is the nth items you want to skip. Default = 0;
• limit is the number of recipes you want. Default is all of them.
• Authentication: [User]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

{
    "recipes": [
        {
            "id": [INTEGER],
            "sourceUrl": [STRING],
            "cheap": [BOOLEAN],
            "vegan": [BOOLEAN],
            "cookingMinutes": [INTEGER],
            "title": [STRING],
            "dairyFree": [BOOLEAN],
            "externalId": [INTEGER],
            "preparationMinutes": [INTEGER],
            "extendedIngredients": [STRING],
            "vegetarian": [BOOLEAN],
            "createdAt": [STRING],
            "updatedAt": [STRING]
        },
    ]
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {403: 'Forbidden'}

4.2 Get ingredients for recipe: [GET] /v1/recipe/:id/ingredients

Description

• Authentication: [User]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

{
    "ingredients": [
        {
          "originalString": [STRING],
          "aisle": [STRING],
          "name": [STRING],
          "metaInformation": [ [STRING], ],
          "image": [STRING],
          "unitLong": [STRING],
          "unitShort": [STRING],
          "amount": [INTEGER],
          "id": [INTEGER],
          "unit": [STRING],
        }
    ]
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {403: 'Forbidden'}

4.3 Add ingredients: [GET] /v1/recipe/:id/add

Description

• Authentication: [User]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

{
    "list": {
    "id": [INTEGER],
    "name": [STRING],
    "description": [STRING],
    "createdAt": [STRING],
    "updatedAt": [STRING],
    "userId": [INTEGER],
    "items": [
        {
            "id": [INTEGER],
            "name": [STRING],
            "quantity": [INTEGER],
            "price": [INTEGER],
            "expiration": [STRING],
            "createdAt": [STRING],
            "updatedAt": [STRING],
            "listId": [INTEGER]
        }
    ]
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {403: 'Forbidden'}

4.4 Suggest recipes: [GET] /v1/recipe/suggest[?q=[INTEGER 1-100] DEFAULT 100]

Description

• Percentage is the percent of ingredients that must intersect for it to be in the resulting set
• Authentication: [User]

Request:

• Header: {'Authorization': 'Bearer TOKEN'}

Response:

{
    "recipes": [
        {
            "id": [INTEGER],
            "sourceUrl": [STRING],
            "cheap": [BOOLEAN],
            "vegan": [BOOLEAN],
            "cookingMinutes": [INTEGER],
            "title": [STRING],
            "dairyFree": [BOOLEAN],
            "externalId": [INTEGER],
            "preparationMinutes": [INTEGER],
            "extendedIngredients": [STRING],
            "vegetarian": [BOOLEAN],
            "createdAt": [STRING],
            "updatedAt": [STRING]
        },
    ]
}

Response Status Codes:

• Success Code: {200: 'Success'}
• Error Code: {403: 'Forbidden'}