Skip to main content

Getting started

This guide will help you get the Pagemark API up and running quickly for development.

Prerequisites​

To run the Pagemark API, you need:

  • Python: Version 3.8 or higher.

Install​

Follow these steps to set up your development environment and install the project dependencies.

  1. Clone the repository (if you haven't already):

    git clone <repository-url>
    cd pagemark-api # Or whatever your project directory is named

  2. Create and activate a virtual environment:

    It's good practice to isolate your project dependencies.

    python3 -m venv .venv
    source .venv/bin/activate

  3. Install dependencies:

    pip install -r requirements.txt

Hello world​

Let's start the API server and make a test request.

  1. Run the server:

    python run.py

    The API will start on http://localhost:5000. You should see output indicating the Flask development server is running.

  2. Create your first bookmark:

    Open a new terminal window (keep the server running in the first one) and make a POST request to create a bookmark.

    curl -X POST -H "Content-Type: application/json" -d '{"url": "https://example.com/my-bookmark", "title": "My First Bookmark"}' http://localhost:5000/api/bookmarks

    You should receive a JSON response similar to this, confirming the bookmark creation:

    {
      "created_at": "...",
      "description": "",
      "id": "...",
      "metadata": {},
      "status": "active",
      "tags": [],
      "title": "My First Bookmark",
      "url": "https://example.com/my-bookmark",
      "updated_at": "..."
    }

  3. List your bookmarks:

    Now, retrieve all bookmarks to see the one you just created.

    curl http://localhost:5000/api/bookmarks

    The response will include your new bookmark:

    {
      "bookmarks": [
        {
          "created_at": "...",
          "description": "",
          "id": "...",
          "metadata": {},
          "status": "active",
          "tags": [],
          "title": "My First Bookmark",
          "url": "https://example.com/my-bookmark",
          "updated_at": "..."
        }
      ],
      "total": 1
    }

Configure​

The Pagemark API uses environment variables for configuration, which can be loaded from a .env file.

  1. Create a .env file:

    In the root of your project directory, create a file named .env.

    touch .env

  2. Add configuration:

    Open .env and add your desired environment variables. For example, to set a SECRET_KEY (important for production):

    # .env
    SECRET_KEY="your-strong-secret-key-here"
    # DEBUG=True # Uncomment for development debugging

    The application will automatically pick up these variables when python-dotenv is installed (which it is, via requirements.txt).

Verify​

To quickly verify that the API server is running and accessible, you can make a simple GET request.

curl http://localhost:5000/api/bookmarks

A successful response (even an empty list of bookmarks) indicates the server is operational. If you get a connection error, the server might not be running or is on a different port.

Next steps​

  • Explore all available API endpoints in the app.
  • Learn about advanced configuration options in the Application Configuration.
  • Understand the project's architecture and how to contribute in the Overview.

Troubleshooting​

  • "command not found: python3" or "pip": Ensure Python 3 is installed and correctly added to your system's PATH. You might need to use python instead of python3 or pip instead of pip3 depending on your system's setup.
  • "Address already in use": This means another process is already using port 5000. You can either stop the other process or configure the Flask app to run on a different port (see Application Configuration for details).
  • Virtual environment issues: If you encounter errors related to missing packages after activation, ensure you ran pip install -r requirements.txt after activating the virtual environment. If in doubt, delete the .venv directory and start the "Install" steps again.
  • Missing .env variables: If your configuration changes aren't taking effect, ensure your .env file is in the project root and the server was restarted after changes.