URL Bookmark API

A RESTful API that provides Bookmarked URLs to visit later.

The backend code follows PEP-8 style guidelines.

Getting Started

• Base URL: https://url-bookmark.herokuapp.com/

• Authentication: https://bit.ly/2Ipsvrl

It's recommended to run the project inside a virtual environment. To do this, run the following:

virtualenv venv (For first time only)
source venv/bin/activate

From the /backend folder run pip3 install requirements.txt. All required packages are included in the requirements file.

To run the application, run the following commands inside the /backend folder:

export FLASK_APP=api.py
export FLASK_ENV=development
flask run

For Windows system, replace export command with set (i.e. set FLASK_APP=api.py)

Frontend (Not Applicable)

If applicable; inside the /frontend folder, run the following commands to start the client:

npm install (Only once to install dependencies)
npm start

By default, the frontend will run on localhost:3000.

Tests

To run tests, go back to the project folder and run the following commands:

dropdb bookmark_test
createdb bookmark_test
python unit_tests.py

Omit the dropdb command for the first time running the tests.

Roles and Permissions

The current permissions are: get:categories, post:bookmarks, patch:bookmarks, and delete:bookmarks. The current roles for this web app are user and admin in the following arrangement:

• user role has the following permissions: get:categories and post:bookmarks.
• admin role has all the permissions listed above.

Error Handling

Errors are returned as JSON obejcts in the following format:

{
  "error": 404, 
  "message": "not found",
  "success": false
}

The Error types the API returns when requests fail are:

HTTP Status Code	Response
400	Bad Request
401	Auth Error
403	Unauthorized
404	Not Found
405	Method Not Allowed
422	Unprocessable Entity

Endpoints

GET /bookmarks

Returns a list of bookmarked URLs. Results are paginated in groups of 5. Include a query argument to choose page number (e.g. ?page=1).

• Sample Request:

curl -X GET https://url-bookmark.herokuapp.com/bookmarks

• Sample Response:

{
    "bookmarks": [
        {
            "id": 1,
            "title": "Personal Site",
            "url": "https://rayan.dev"
        },
        {
            "id": 2,
            "title": "Saudi Network Information Center",
            "url": "https://nic.sa"
        },
        {
            "id": 3,
            "title": "Work Site",
            "url": "https://citc.gov.sa"
        },
        {
            "id": 4,
            "title": "GitHub Account",
            "url": "https://github.com/RayanAlkhelaiwi"
        },
        {
            "id": 5,
            "title": "Twitter",
            "url": "https://twitter.com"
        }
    ],
    "success": true
}

GET /categories

Returns a list of categories of the bookmarks and their importance. Results are paginated in groups of 5. Include a query argument to choose page number (e.g. ?page=1).

• Sample Request:

curl -X GET https://url-bookmark.herokuapp.com/categories

• Sample Response:

{
    "categories": [
        {
            "id": 1,
            "important": false,
            "type": "Personal"
        },
        {
            "id": 2,
            "important": true,
            "type": "Work"
        }
    ],
    "success": true
}

POST /bookmarks

Creates a new URL bookmark by submitting the information for a title and its URL. It returns the submitted information, success value and the stored bookmarks.

• Sample Request:

curl -X POST -H "Content-Type: application/json" -d '{"title":"Personal Site", "url":"https://rayan.dev"}' https://url-bookmark.herokuapp.com/bookmarks

• Sample Response:

{
    "bookmarks": [
        {
            "id": 1,
            "title": "Saudi Network Information Center",
            "url": "https://nic.sa"
        },
        {
            "id": 2,
            "title": "Work",
            "url": "https://citc.gov.sa"
        },
        {
            "id": 3,
            "title": "GitHub Account",
            "url": "https://github.com/RayanAlkhelaiwi"
        },
        {
            "id": 4,
            "title": "Twitter",
            "url": "https://twitter.com"
        },
        {
            "id": 5,
            "title": "Personal Site",
            "url": "https://rayan.dev"
        }
    ],
    "created": {
        "id": 5,
        "title": "Personal Site",
        "url": "https://rayan.dev"
    },
    "success": true
}

PATCH /bookmarks/{bookmark_id}

Updates the bookmark info using the bookmark's ID. Returns the ID of the deleted bookmark and the success value.

• Sample Request:

curl -X PATCH -H "Content-Type: application/json" -d '{"title":"Personal Site", "url":"https://rayan.dev"}' https://url-bookmark.herokuapp.com/bookmarks/5

• Sample Response:

{
    "bookmark": {
        "id": 5,
        "title": "Personal Site",
        "url": "https://rayan.dev"
    },
  "success": true
}

DELETE /bookmarks/{bookmark_id}

Deletes the bookmark with the given ID. Returns the ID of the deleted bookmark and the success value.

• Sample Request:

curl -X DELETE https://url-bookmark.herokuapp.com/bookmarks/4

• Sample Response:

{
  "deleted": 4,
  "success": true
}