[GH-ISSUE #769] "Edit bookmark" API docs do not mention required fields correctly #367

New issue

Closed

opened 2026-02-25 23:34:04 +03:00 by kerem · 0 comments

kerem commented

2026-02-25 23:34:04 +03:00

Owner

Originally created by @msfjarvis on GitHub (Oct 27, 2023).
Original GitHub issue: https://github.com/go-shiori/shiori/issues/769

Data

Shiori version: v1.5.5
Database Engine: SQLite
Operating system: Linux
CLI/Web interface/Web Extension: API

Describe the bug / actual behavior

The API docs for the edit bookmark action say that you need to provide an id to identify the bookmark being edited, and then provide the modified fields.

After creating a bookmark, if I try to edit it via the API and introduce a tag with the following JSON body

{
  "id": 1,
  "tags": [
    {
      "name": "examples"
    }
  ]
}

The server returns a HTTP 500 error with the message: title must not be empty.
After I add the title, I still get an HTTP 500 error but with the message: failed to clean URL: URL is not valid

After both title and url are added to the JSON, API request succeeds

{
  "id": 1,
  "title": "Example Domain",
  "url": "https://example.com",
  "tags": [
    {
      "name": "examples"
    }
  ]
}

This is in disagreement with the documentation since in this situation neither the title nor url were being modified, and hence should not have been required.

Expected behavior

The API docs either mention that the title and URL fields are always required, or the server is modified to match the documentation.

Notes

I discovered the problem from integration testing while trying to write an API client for Shiori to use in my Android app

I've gotten rid of the "Steps to reproduce" heading since it seemed tedious and unnecessary to note down all the steps I did in httpie, but I can do it if it helps, just ask.

Originally created by @msfjarvis on GitHub (Oct 27, 2023). Original GitHub issue: https://github.com/go-shiori/shiori/issues/769 ## Data - **Shiori version**: v1.5.5 - **Database Engine**: SQLite - **Operating system**: Linux - **CLI/Web interface/Web Extension**: API ## Describe the bug / actual behavior The API docs for the [edit bookmark action](https://github.com/go-shiori/shiori/blob/c64e858a231f3f8a2391f97e9ab71aae30bd137b/docs/API.md#edit-bookmark) say that you need to provide an `id` to identify the bookmark being edited, and then _provide the modified fields_. After creating a bookmark, if I try to edit it via the API and introduce a tag with the following JSON body ```json { "id": 1, "tags": [ { "name": "examples" } ] } ``` The server returns a HTTP 500 error with the message: `title must not be empty`. After I add the title, I still get an HTTP 500 error but with the message: `failed to clean URL: URL is not valid` After both title and url are added to the JSON, API request succeeds ```json { "id": 1, "title": "Example Domain", "url": "https://example.com", "tags": [ { "name": "examples" } ] } ``` This is in disagreement with the documentation since in this situation neither the title nor url were being modified, and hence should not have been required. ## Expected behavior The API docs either mention that the title and URL fields are always required, or the server is modified to match the documentation. ## Notes I discovered the problem from integration testing while [trying to write an API client for Shiori](https://github.com/msfjarvis/compose-lobsters/pull/406) to use in my [Android app](https://play.google.com/store/apps/details?id=dev.msfjarvis.claw.android) I've gotten rid of the "Steps to reproduce" heading since it seemed tedious and unnecessary to note down all the steps I did in [httpie](https://httpie.io), but I can do it if it helps, just ask.