quicknotes/specs/api.md

API Specification

Overview

QuickNotes provides a RESTful API for communication between the frontend and backend. The API is built using the Gin web framework and follows REST principles.

Base URL

All API endpoints are prefixed with /api.

Authentication

The API does not currently implement authentication as it is designed for local use.

Response Format

API responses are formatted as JSON with the following structure:

• For successful responses returning data:

  {
    "field1": "value1",
    "field2": "value2",
    ...
  }
  

• For successful responses returning arrays:

  [
    {
      "field1": "value1",
      "field2": "value2",
      ...
    },
    ...
  ]
  

• For error responses:

  {
    "error": "Error message"
  }
  

Status Codes

The API uses standard HTTP status codes:

• 200 OK: The request was successful
• 400 Bad Request: The request was invalid
• 404 Not Found: The requested resource was not found
• 500 Internal Server Error: An error occurred on the server

Endpoints

Notes

List Notes

• URL: /api/notes
• Method: GET
• Description: Get a list of all notes
• Response: Array of Note objects

  [
    {
      "id": "note-id",
      "title": "Note Title",
      "content": "Note content in Markdown",
      "createdAt": "2023-01-01T12:00:00Z",
      "updatedAt": "2023-01-01T12:00:00Z"
    },
    ...
  ]
  

Create Note

• URL: /api/notes
• Method: POST
• Description: Create a new note
• Request Body: Note object without ID

  {
    "title": "Note Title",
    "content": "Note content in Markdown"
  }
  

• Response: Created Note object with ID

  {
    "id": "note-id",
    "title": "Note Title",
    "content": "Note content in Markdown",
    "createdAt": "2023-01-01T12:00:00Z",
    "updatedAt": "2023-01-01T12:00:00Z"
  }
  

Get Note

• URL: /api/notes/:id
• Method: GET
• Description: Get a specific note by ID
• URL Parameters: id - ID of the note
• Response: Note object

  {
    "id": "note-id",
    "title": "Note Title",
    "content": "Note content in Markdown",
    "createdAt": "2023-01-01T12:00:00Z",
    "updatedAt": "2023-01-01T12:00:00Z",
    "linksTo": [
      {
        "id": "linked-note-id",
        "title": "Linked Note Title"
      }
    ],
    "linkedBy": [
      {
        "id": "linking-note-id",
        "title": "Linking Note Title"
      }
    ]
  }
  

Update Note

• URL: /api/notes/:id
• Method: PUT
• Description: Update a specific note
• URL Parameters: id - ID of the note
• Request Body: Note object with updated fields

  {
    "title": "Updated Title",
    "content": "Updated content"
  }
  

• Response: Updated Note object

  {
    "id": "note-id",
    "title": "Updated Title",
    "content": "Updated content",
    "createdAt": "2023-01-01T12:00:00Z",
    "updatedAt": "2023-01-02T12:00:00Z"
  }
  

Delete Note

• URL: /api/notes/:id
• Method: DELETE
• Description: Delete a specific note
• URL Parameters: id - ID of the note
• Response: Empty response with status code 200

Import Obsidian Vault

• URL: /api/notes/import
• Method: POST
• Description: Import notes from an Obsidian vault
• Request Body: Multipart form with a file field containing the zip file
• Response: Import result

  {
    "imported": 42
  }
  

Readlist

List Read Later Items

• URL: /api/readlist
• Method: GET
• Description: Get a list of all read later items
• Query Parameters:
  • status - Filter by status (read, unread, archived, unarchived)
• Response: Array of ReadLaterItem objects

  [
    {
      "id": "item-id",
      "url": "https://example.com/article",
      "title": "Article Title",
      "description": "Article description",
      "createdAt": "2023-01-01T12:00:00Z",
      "updatedAt": "2023-01-01T12:00:00Z",
      "readAt": null,
      "archivedAt": null
    },
    ...
  ]
  

Save Article

• URL: /api/readlist
• Method: POST
• Description: Save a new article
• Request Body: ReadLaterItem object with URL

  {
    "url": "https://example.com/article"
  }
  

• Response: Created ReadLaterItem object

  {
    "id": "item-id",
    "url": "https://example.com/article",
    "title": "Article Title",
    "content": "Article content in HTML",
    "description": "Article description",
    "createdAt": "2023-01-01T12:00:00Z",
    "updatedAt": "2023-01-01T12:00:00Z",
    "readAt": null,
    "archivedAt": null
  }
  

Get Article

• URL: /api/readlist/:id
• Method: GET
• Description: Get a specific article by ID
• URL Parameters: id - ID of the article
• Response: ReadLaterItem object

  {
    "id": "item-id",
    "url": "https://example.com/article",
    "title": "Article Title",
    "content": "Article content in HTML",
    "description": "Article description",
    "createdAt": "2023-01-01T12:00:00Z",
    "updatedAt": "2023-01-01T12:00:00Z",
    "readAt": null,
    "archivedAt": null
  }
  

Mark as Read/Unread

• URL: /api/readlist/:id/read or /api/readlist/:id/unread
• Method: PUT
• Description: Mark an article as read or unread
• URL Parameters: id - ID of the article
• Response: Updated ReadLaterItem object

Archive/Unarchive

• URL: /api/readlist/:id/archive or /api/readlist/:id/unarchive
• Method: PUT
• Description: Archive or unarchive an article
• URL Parameters: id - ID of the article
• Response: Updated ReadLaterItem object

Feeds

List Feeds

• URL: /api/feeds
• Method: GET
• Description: Get a list of all feeds
• Response: Array of Feed objects

  [
    {
      "id": "feed-id",
      "title": "Feed Title",
      "url": "https://example.com/feed.xml",
      "description": "Feed description",
      "siteUrl": "https://example.com",
      "imageUrl": "https://example.com/logo.png",
      "lastFetched": "2023-01-01T12:00:00Z",
      "createdAt": "2023-01-01T12:00:00Z",
      "updatedAt": "2023-01-01T12:00:00Z"
    },
    ...
  ]
  

Subscribe to Feed

• URL: /api/feeds
• Method: POST
• Description: Subscribe to a new feed
• Request Body: Feed object with URL

  {
    "url": "https://example.com/feed.xml"
  }
  

• Response: Created Feed object

List Entries

• URL: /api/feeds/entries or /api/feeds/:id/entries
• Method: GET
• Description: Get a list of entries from all feeds or a specific feed
• URL Parameters: id (optional) - ID of the feed
• Query Parameters:
  • status - Filter by status (read, unread)
  • limit - Maximum number of entries to return
  • offset - Offset for pagination
• Response: Array of Entry objects

  [
    {
      "id": "entry-id",
      "feedId": "feed-id",
      "title": "Entry Title",
      "url": "https://example.com/article",
      "content": "Entry content in HTML",
      "summary": "Entry summary",
      "author": "Author Name",
      "published": "2023-01-01T12:00:00Z",
      "updated": "2023-01-01T12:00:00Z",
      "readAt": null,
      "createdAt": "2023-01-01T12:00:00Z",
      "updatedAt": "2023-01-01T12:00:00Z"
    },
    ...
  ]
  

Refresh Feeds

• URL: /api/feeds/refresh or /api/feeds/:id/refresh
• Method: POST
• Description: Refresh all feeds or a specific feed
• URL Parameters: id (optional) - ID of the feed
• Response: Refresh result

  {
    "newEntries": 5
  }
  

Error Handling

The API handles errors by returning appropriate HTTP status codes and error messages:

{
  "error": "Detailed error message"
}

Common error scenarios:

1. Invalid Input: Returns 400 Bad Request
2. Resource Not Found: Returns 404 Not Found
3. Server Error: Returns 500 Internal Server Error

Rate Limiting

The API does not currently implement rate limiting as it is designed for local use.

Versioning

The API does not currently implement versioning. Future versions may include a version prefix in the URL path (e.g., /api/v1/notes).