====================================

The andela shopping list api that allows users plan shopping experiences.

https://andela-flask-api.herokuapp.com/**version**/documentation

To look at the api version 1 documentation, use v1 in the place of "version" like below

https://andela-flask-api.herokuapp.com/v1/documentation

https://andela-flask-api.herokuapp.com/

Python v3.5.2 used

After cloning, create a virtual environment and install the requirements. For Linux and Mac users:

$ virtualenv venv
$ source venv/bin/activate
(venv) $ pip install -r requirements.txt

If you are on Windows, then use the following commands instead:

$ virtualenv venv
$ venv\Scripts\activate
(venv) $ pip install -r requirements.txt

Once installation is complete, we need to set up the postgres database.

Postgres installation

Use the OS link that applies to you, if it's not available please go to https://www.google.com

http://www.techrepublic.com/blog/diy-it-guy/diy-a-postgresql-database-server-setup-anyone-can-handle/ [any debian distribution]

https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-16-04 [ubuntu 16.04]

https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-14-04 [ubuntu 14.04]

https://labkey.org/Documentation/wiki-page.view?name=installPostgreSQLWindows [windows]

https://www.postgresql.org/download/windows/ [official docs windows]

https://www.postgresql.org/download/macosx/ [Mac osx]

If you're more comfortable with a desktop application give this a shot https://www.postgresapp.com

Database Setup

To set up the database, please follow this document https://www.codementor.io/devops/tutorial/getting-started-postgresql-server-mac-osx .

Follow the following instructions to get your database up and running. (Begin from step 3 if postgres is already installed, MacOsX users can use it to both install and set up)

1. Create role ‘Vince’ with password ‘vince’ (Step 3 A)
2. Give this role a privilege of CREATEDB (Step 3 A)
3. Create DB with name ‘andela-flask-api’ (Step 3 B)

The following must be done with ALL the above steps completed. Execute these commands in the order they appear.

#4 must be run only once

4. python manage.py db init

#5 and #6 must be every time you make changes to the application models

5. python manage.py db migrate
6. python manage.py db upgrade

To run the server use the following command:

(andela-falsk-api) $ python app/views.py
 * Running on http://127.0.0.1:5000/
 * Restarting with reloader

Then from a different terminal window you can send requests or an API test client like Postman.

To run the application tests, use the following command:

(andela-falsk-api) $ py.test --cov=app app/tests/

The following routes are accessible publicly i.e. you don't need to log in.

• POST /auth/register

  Register a new user.
  The body must contain a JSON object that defines email, ``username, password` and `password2` fields.
  The passwords must match and the email should have the proper email format
  On success a status code 201 is returned. The body of the response contains a JSON object with the newly added user.
  On failure status code 200 is returned with a JSON object with an error message.
  Notes:

  • The password is hashed before it is stored in the database. Once hashed, the original password is discarded.
  • In a production deployment secure HTTP must be used to protect the password in transit.

• POST /auth/login

  Login to access protected routes.
  The body must contain a JSON object that defines username and password fields.
  On success a status code 200 is returned. The body of the response contains a JSON object with the a success message and a token that should be used for subsequent requests to protected routes.
  On failure status code 200 (bad request) is returned with a JSON object with an error message
  Notes: - The token is valid for 10 minutes - Good news is you can use this token to generate other tokens through the /api/token route and therefore have an uninterrupted experience with the service

• POST /auth/logout

  Logs you out and invalidates the token assigned to you.
  

• POST /auth/reset-password

  Submit you email address to reset your password.
  The body must contain a JSON object that defines email of a valid active user.
  On success a status code 200 is returned. The body of the response contains a JSON object with a success message.
  On failure status code 404 (bad request) or a status code 200 with an error message is returned.
  Notes:

  • If successful, an email is sent to your email address with a link that will allow you to set a new password
  • This link is invalidated 10 minutes after sending the email.

• POST /auth/reset-password/{some-long-identification-token}

  Reset password endpoint.
  The body must contain a JSON object that defines password and password_confirm fields.
  On success a status code 200 is returned. The body of the response contains a JSON object with a success message. You will be able to login with your new details after this.
  On failure status code
  - 404 (bad request) is returned if the token used does not exists.
  - 401 (Unauthorized) is returned if the token is used after 10 minutes beyond which its invalid.
  - 200 is returned. The body of the response contains a JSON object with an error message..
  

The following routes are not accessible publicly i.e. you need to log in and use your token returned on login to access them.

• POST /shoppinglists

  Add a new shopping list.
  The body must contain a JSON object that defines a name field.
  On success a status code 201 is returned. The body of the response contains a JSON object with the newly added list.
  On failure status code
  - 200 is returned with a JSON object with an error message.
  - 401 (unauthorized) is returned if the user is not logged in or the token is not sent with the request.

• GET /shoppinglists

  Get all your shopping lists.
  An optional list_id get parameter can be used to retrieve a particular list
  On success a status code 200 is returned. The body of the response contains a JSON object with all your shopping lists.
  On failure status code 401 (unauthorized) is returned if the user is not logged in or the token is not sent with the request.
  

• GET /shoppinglists/{id}

  Get all shopping list items under list with id : id .
  An optional item_id get parameter can be used to retrieve a particular item
  On success a status code 200 is returned. The body of the response contains a JSON object with the items under the specified list.
  On failure status code
  - 404 (bad request) is returned if the id provided does not belong to any existing list.
  - 401 (unauthorized) is returned if the user is not logged in or the token is not sent with the request.
  - 500 is returned if the id is not a valid integer.
  - 200 is returned with a JSON object with an 'errors' attribute.
  

• PUT /shoppinglists/{id}

  Update shopping list with id : id .
  The body must contain a JSON object that defines a name field.
  On success a status code 201 is returned. The body of the response contains a JSON object with a success attribute.
  On failure status code
  - 404 (bad request) is returned if the id provided does not belong to any existing list.
  - 401 (unauthorized) is returned if the user is not logged in or the token is not sent with the request.
  - 500 is returned if the id is not a valid integer.
  - 200 is returned with a JSON object with an 'errors' attribute.
  

• DELETE /shoppinglists/{id}

  Delete shopping list with id : id .
  On success a status code 202 is returned. The body of the response contains a JSON object with a success attribute.
  On failure status code
  - 404 (bad request) is returned if the id provided does not belong to any existing list.
  - 401 (unauthorized) is returned if the user is not logged in or the token is not sent with the request.
  - 500 is returned if the id is not a valid integer.
  - 200 is returned with a JSON object with an 'errors' attribute.
  

• POST /shoppinglists/{id}/items/

  Add a new shopping list item.
  The body must contain a JSON object that defines name and amount fields.
  On success a status code 201 is returned. The body of the response contains a JSON object with the newly added shopping list item.
  On failure status code
  - 404 (bad request) is returned if the id provided does not belong to any existing list.
  - 401 (unauthorized) is returned if the user is not logged in or the token is not sent with the request.
  - 500 is returned if the id is not a valid integer.
  - 200 is returned with a JSON object with an 'errors' attribute.
  

• PUT /shoppinglists/{id}/items/{item_id}

  Update a shopping list item.
  The body must contain a JSON object that defines name and amount fields.
  On success a status code 200 is returned. The body of the response contains a JSON object with a success attribute.
  On failure status code
  

  • 404 (bad request) is returned if the id and item_id provided does not belong to any existing list or item respectively.
    
  • 401 (unauthorized) is returned if the user is not logged in or the token is not sent with the request.
    
  • 500 is returned if the id or item_id is not a valid integer.
    
  • 200 is returned with a JSON object with an 'errors' attribute.
    

• DELETE /shoppinglists/{id}/items/{item_id}

  Register a new user.
  On success a status code 202 is returned. The body of the response contains a JSON object with a success property.
  On failure status code
  

  • 404 (bad request) is returned if the id or item_id provided does not belong to any existing list or item respectively.
    
  • 401 (unauthorized) is returned if the user is not logged in or the token is not sent with the request.
    
  • 500 is returned if the id is not a valid integer.
    
  • 200 is returned with a JSON object with an 'errors' attribute.
    

• PUT /shoppinglists/{id}/items/{item_id}/checkbox

  Update a shopping list item bought state.
  On success a status code 200 is returned. The body of the response contains a JSON object with a success attribute.
  On failure status code
  

  • 404 (bad request) is returned if the id and item_id provided does not belong to any existing list or item respectively.
    
  • 401 (unauthorized) is returned if the user is not logged in or the token is not sent with the request.
    
  • 500 is returned if the id or item_id is not a valid integer.
    
  • 200 is returned with a JSON object with an 'errors' attribute.