Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

API.html: the `Remove Properties` example calls `/api/set`, and `Patch Update` documents `null` as storing null

未关闭 适合新手
  • 哪里不对？
#311 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

评估

难度
2/5
预计耗时
1-3 小时
新手友好度
88/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
javascript
领域
api, documentation

调研方向

从 public/API.html 中的 Patch Update 和 Remove Properties 示例开始，然后将其措辞和 URL 与 controllers/patchUpdate.js、controllers/patchUnset.js 以及 routes/api-routes.js 进行比较。完成的标准是删除示例使用 /api/unset，将 null 的行为记录为删除，并且周围的 endpoint 示例保持一致。

由索引模型根据 Issue 内容生成。

描述

bug documentation

Summary

Two PATCH sections of public/API.html contradict the controllers they document. Both are in the copy-paste path, and one of them documents the wrong endpoint entirely.

  • The Remove Properties Javascript example calls /api/set. The section documents /unset, its prose is right, and its payload is an unset payload — but the fetch URL is https://devstore.rerum.io/v1/api/set. Anyone copying the example sends a removal payload to the add-only endpoint.
  • Patch Update documents {"key": null} as storing null. It says the value "will be set to null instead of removing the property". controllers/patchUpdate.js deletes the key.

The third API.html error I found — the default of 10 records at line 506 — is already tracked in #305, so it is not repeated here.

Why this matters

The /unset example is the wrong endpoint, not a typo in prose. routes/patchUnset.js serves /api/unset (mounted at routes/api-routes.js:61), and GET /v1/api describes /unset as "PATCH - Update the body an existing object by removing an existing property." The example's own body — "existing_property": null with an "unmatched_property" noted as ignored — is exactly the unset contract described three lines above it. Sent to /api/set it is a silent no-op: controllers/patchSet.js keeps only keys that are not already present, so existing_property is filtered out, nothing survives, and the server returns the original object with a 200 and the same @id. The caller sees success and the property is still there.

Copy-paste is the documented path. These blocks are the worked examples for the endpoint, and they are extracted verbatim by downstream consumers. A tool of ours that builds a corpus from API.html ingested this example and learned /api/set as the endpoint for removing a property; that is our bug to fix on our side, but it is evidence that the block travels intact.

The null claim is inverted, and null is load-bearing for both endpoints. controllers/patchUpdate.js:58-63 branches on the value:

for (let k in objectReceived) {
    if (originalObject.hasOwnProperty(k)) {
        if (objectReceived[k] === null) {
            delete patchedObject[k]
        }
        else {
            patchedObject[k] = objectReceived[k]
        }
    }

So /patch with null removes the key. /unset requires null to remove anything at all (controllers/patchUnset.js:61-70), which Remove Properties states correctly. A reader who trusts Patch Update believes RERUM stores JSON nulls, which it never does through this route.

Affected lines

All line numbers at 8e4b673d.

File Line Current Should be
public/API.html 1413 fetch("https://devstore.rerum.io/v1/api/set", { in the Remove Properties example .../v1/api/unset
public/API.html 1249-1250 "If {"key":null} is submitted, the value for property "key" will be set to null instead of removing the property." the key is removed from the new version

Proposed change

  • API.html:1413 — change the URL to https://devstore.rerum.io/v1/api/unset. Nothing else in the block needs to move; the payload and the surrounding prose already describe /unset.
  • API.html:1249-1250 — replace with a sentence matching the controller, e.g. "If {"key":null} is submitted, property key is removed from the resulting record. To change a value, send the new value; to add a key that does not exist yet, use /set."
  • Worth a pass over the other jsExample blocks for the same class of error: each example's URL should be checked against the endpoint its section documents. These two were found by diffing the examples against the controllers rather than by reading the page.
主要语言
JavaScript
星标
3
派生
6
平均合并
14 分钟
30 天内合并 PR
2

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

CenterForDigitalHumanities/rerum_server_nodejs 的其他 Issue

查看 CenterForDigitalHumanities/rerum_server_nodejs 的全部 Issue

相似的 Issue

更多 JavaScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。