In Anqi CMS, obtaining document details is a very frequent operation in our daily operation. Usually, we will use the unique numeric identifier of the document.idor its user-friendly URL aliasfilenameto request document data. When developers call/api/archive/detailthe interface, they may encounter a question: if I provide bothidandfilenameWhich of these parameters, will the system prioritize to locate the document I want?

Understanding this priority strategy is very important for ensuring the accuracy of API calls and optimizing the front-end display logic.

Key parameter in the document detail interface.

Let's review the AnQi CMS document details interface (/api/archive/detail) aboutidandfilenameparameter descriptions:

  • id: Type isintIt is the internal unique identifier of the document. The document mentions: 'Mandatory, if filename is provided, ID is not required.'
  • filename: Type isstringThe URL alias of the document, usually a human-readable string that is beneficial for SEO.The document mentions: "Document URL alias, document ID or filename, either one".

From these descriptions, we can see some key information.idIt is usually necessary, but its necessity lies infilenameIt can be exempted when it exists. AndfilenameIt clearly states withidis a 'either/or' relationship.

idwithfilenameThe preferred strategy

By deep analysis of the document and practical experience, the document detail interface of Anqi CMS receivesidandfilenameparameters,It will usefilenameparameters to find the document.

This means that if the request includesidfor example:id=123), andfilenamefor example:filename=my-awesome-article), the system will first try to locate the document based onfilename(my-awesome-article) Only when throughfilenameUnable to find the corresponding document (for examplefilenamedoes not exist or does not match) when the system may (but the document does not explicitly state that there is a fallback mechanism, so it should not be relied upon) consider usingidEven if it returns an error directly.

Why should it befilenamePriority?

This design is logical and suitable for actual application scenarios:

  1. Semanticization and uniqueness: filenameIt usually represents the semantic URL of a document, which has higher value for external links and SEO. In terms of design, a document'sfilenameThe alias should be unique, it represents the "identity" of the document in the public access path.
  2. Consistency of front-end presentation:The website front-end usually goes throughfilenameTo display the article link. If the user accesses through such a link and also attaches something that may be used internally for debugging,idthe system uses it first.filenameIt ensures that the user sees the content that matches their access path.
  3. Flexible parameter design:DeclarationidInfilenameIt can be omitted when present, which meansfilenameHas sufficient ability to independently identify a document. If both are provided, and assumingfilenameis valid, then using it as the main basis of identification is efficient and clear.

Advice in practical application

Understanding this priority strategy in practical development and content operations can help us call APIs and design systems more accurately:

  • Avoid redundancy:If you have already passedfilenameThere is no need to pass it again if it can uniquely identify a documentid. Reducing unnecessary parameter passing can make API requests more concise and clear.
  • Maintain consistency:When providing document details externally, prioritize the use offilenameconstructing URLs, and thenfilenamemake API calls with parameters, which can maintain consistency between internal logic and external display.
  • Handle special cases:If you are in some internal tools or debugging scenarios, onlyidAndfilenameuncertain or possibly empty, then only passidobviously the correct choice.

In short, the Anqi CMS document detail interface isidandfilenameWhen both exist, it will befilenamedominant. This reflects the emphasis of the content management system on semantic URLs and external access logic.

Frequently Asked Questions (FAQ)

Q1: If I provided bothidandfilename, but they point to different documents, what will happen?A1: According to the priority strategy of Anqi CMS, the system will try to go throughfilenameTo search for a document. IffilenameThen a valid document was found successfully,idThe value (even if it points to another document) is usually ignored. To avoid potential confusion and errors, it is strongly recommended to only provide in API requests.idorfilenameof them, and ensure its accuracy to match the specific document you wish to obtain.

Q2: In what circumstances should I only useidand not usefilename?A2: How many scenarios are suitable for using onlyid:

1.  **内部系统集成：** 在不需要对外暴露友好URL的内部应用或服务间调用时，`id` 作为纯数字标识符，更加稳定和高效。
2.  **数据迁移或批量处理：** 当你处理大量数据，并且 `filename` 可能不规范或需要重新生成时，使用稳定的 `id` 可以避免潜在的查找问题。
3.  **`filename` 不确定或不存在：** 例如，用户通过某种方式只获得了文档ID，或者文档的 `filename` 尚未设置或已经失效。

Q3:filenameHow does AnQi CMS ensure its uniqueness to support it as a priority identification mark?A3:filename(URL alias) is usually automatically generated by the system or manually set by the content editor in AnQi CMS. The system performs a uniqueness check when saving the document to ensure that no duplicates occur under the same model.filenameIf the user entersfilenamealready exists, the system will usually prompt the user to modify it, or add a numerical suffix to the URL to ensure uniqueness. This mechanism ensuresfilenameCan reliably serve as a unique identifier for a document.