What are the types of backend high-frequency interface capabilities, and what should be clarified in the public interface document?

What are the main categories of high-frequency interface capabilities provided by the content management system? According to the purpose of the call, there are four categories: reading class covering document list and details, classification and tags;Write the class to override upload pictures, submit messages and comments; the relationship and configuration class to override friend links, system settings and contact information; the batch class to override import and synchronization.These capabilities constitute the common interface of the public API, the frequent call capabilities of AnQiCMS's interface include document list and details, categories and tags, upload images, messages and comments, friend links, system settings and contact information.The public interface document should not just list 'which interfaces', but rather the parameter specifications, return structures, error codes, and authentication boundaries of each type of interface.

How are high-frequency capabilities categorized?

The read type has the highest call frequency and is most likely to be misused externally because it seems harmless. The key to the document list interface is pagination and filtering criteria: how many items per page, whether the sorting field can be specified externally, and whether drafts and pending release states are included. If these criteria are not clarified, the calling party of the same interface will get completely different data.

Write class involves data storage, including image upload, message and comment submission. This type of document focuses on constraints: allowed formats and volume, frequency limit, how to return review status, and whether it is partial success or overall rejection when failing.

Relationship and configuration classes are usually low-frequency but critical reads, such as friendship links and contact information, external pages and mobile terminals will be used for self-display, field naming and null value handling should be stable.

Batch class is an import interface, used to move historical data from external content management systems or tables into the system, it belongs to a one-time but the highest risk call.

Should the document give parameters or examples

Both are needed, but in a different order. The parameter table solves 'whether it can be connected': name, type, required, value range, default value. The example solves 'how to use it after it is connected': a typical request, a complete return, an error return.

Only provide examples without parameter tables, the caller will guess the boundaries; only provide parameter tables without examples, the semantics of the fields are still ambiguous. It is recommended to write the meanings of the fields in the returned structure one by one, especially for status fields - whether the document is formal, draft, to be published, or in the recycle bin directly determines whether it should be displayed externally. The document status of AnQiCMS is divided into formal documents, drafts, to be published, and recycle bins. Deleting a formal document is to move it to the recycle bin rather than a physical deletion. This level of semantics should be written in the API documentation. If it is not written, the caller will think that the recycle bin does not exist.

Content models need to explain the field differences brought by customization: the names and types of custom fields may differ in different models, and public interfaces need to provide the reading methods of extended fields. AnQiCMS supports custom content models and custom fields, and such sites especially need to clarify the reading methods of extended fields.

Where should authorization and exposure range be written?

Authorization instructions should be written at the beginning of each category, not concentrated at the end of the appendix. Answer three questions: what credentials are needed for this interface, how to pass the credentials, and which roles can call it. The credentials themselves should not provide example values in the document, but use placeholder names instead.

The exposure range needs to be made clear: not all capabilities are suitable for open access. AnQiCMS's MCP interface sets the exposure range based on the intent domain, operations such as backup, upgrade, and multi-site operations are turned off by default, and need to be explicitly enabled; the tool interface is unified based on the intent directory, write operations support round-by-round batch approval, and external clients can see the actions to be executed before confirming. For document authors, this means that the 'capability list' is tiered: publicly readable, writeable with authentication required, and default closed require explicit enablement, the three levels need to be written separately, and cannot be mixed into a single table.

The location of the batch import interface

Bulk import is usually not part of daily interfaces, but it is the entry point for migration and content pipelines. AnQiCMS provides an import interface /api/import/archive, which supports querying whether the content already exists by title, for bulk import scenarios; the site also supports two types of bulk import methods: ZIP compressed packages and Excel spreadsheets.

The document section must at least list four things: file structure and naming conventions, how to handle duplicate titles, whether failed items can be retried, and whether the content after import is a draft or published directly. Listing these four items can prevent external scripts from running repeatedly and causing the same batch of content to be written multiple times.

Common questions

How often is the API document updated?Update each time there is a change in fields, status criteria, or authentication methods, and leave a note in the version history for the caller to trace the change points.

Should all capabilities be made public?Not necessary. By default, only reading and necessary writing capabilities are opened to the outside, and site-wide operations remain in the state that needs to be explicitly enabled.

What is the most easily overlooked when writing an interface?Frequency limits and idempotent agreements. Not specifying them will cause retry scripts to amplify into dirty data directly.

How to notify when the return structure changes?Use version numbers to distinguish between interface versions, retain the old version for a period of time, and mark the obsolescence time and replacement fields in the documentation.