When using the AnQi CMS for website content management, we often deal with various API interfaces. Among them,archiveFiltersThe interface is an important tool for obtaining document filtering conditions. Many users have noticed that in the returned data, initemsIn the list, each filter parameter option (such as "Beijing" and "Shanghai" under "City") istotalalways displayed as0This may be confusing: since it's about 'quantity', why is it0?"ThistotalWhat is the actual purpose of this field?

To understandarchiveFiltersin the interfacetotalWhy do the fields often show as0and its actual meaning, we need to analyze from the design purpose and actual application scenario of the interface.

Firstly,archiveFiltersThe core purpose of the interface is to provide specific modules that can be filtered.Parameter definitionandOption List.It is like a 'filter menu' that tells the front-end page which dimensions of filtering are available (such as 'City', 'Education') and what specific options are available under each dimension (such as 'City' includes 'Beijing', 'Shanghai', etc.).Its main function is to help developers build dynamic filtering interfaces, such as generating dropdown boxes, radio buttons, or checkboxes on the page.

Check carefullyarchiveFiltersThe returned data example shows:

{
  "name": "城市",
  "field_name": "city",
  "items": [
    {
      "label": "全部",
      "total": 0
    },
    {
      "label": "北京",
      "total": 0
    },
    // ...
  ]
}

Here are thetotalThe field is indeed constant:0This is because:archiveFiltersThe original design intention of the interface was to provide a lightweight, fast-response filtering metadata.If this interface always calculates in real-time the number of documents under each filter option (such as the city of 'Beijing') every time it is called, then in the case of large data volumes or complex filter conditions, each request will place a huge burden on the database, leading to slow interface response and severely affecting user experience.Considering that a front-end page may need to load multiple filters, this real-time count is unnecessary overhead in most cases.

Therefore,archiveFiltersoftotalThe field in this context is not used to indicate the actual number of items corresponding to the current filter option, but as areserve fieldor in other words,a placeholderIt is actually used to inform the interface consumers about the future use of this interfacemayWill be used to pass quantity information, or it may have a non-zero value under certain specific configurations, but in the default and general case, it is set to0To ensure the performance and response speed of the interface. It only defines the data structure without providing dynamic business statistics.

Then, if we need to know how many documents are under a certain filter condition, what should we do? At this time, we need to combinearchiveListthe interface to use.archiveListThe interface is used to retrieve a list of documents, it supports passing various filtering parameters, including fromarchiveFilterscustom filtering fields obtained (such as)city/certificate). What's more important is that when you callarchiveListWhen interfacing, if you includetypeparameter settingspage, it will include a field in the returned resultstotalfield, thistotalfield representsthe current filtering conditionsThe total number of documents matched.

For example, if you want to know how many documents there are about the city “Beijing”, you should do this:

  1. Firstly, go througharchiveFiltersand get the “City” filter.field_name(i.e.,)city）and optionslabel(i.e.,)北京).
  2. Then, callarchiveListinterface, passing inmoduleId, and includecity=北京parameters, and settype=page.{域名地址}/api/archive/list?moduleId=1&city=北京&type=page
  3. archiveListThe top-level result of the interfacetotalThe number of documents found under the condition of “Beijing” will be displayed.

This design pattern effectively separates the 'get condition definition' and 'get content and quantity under specific conditions' functionalities, ensuring that each interface has a single responsibility and runs efficiently.archiveFiltersFocused on providing filtering rules, whilearchiveListis responsible for providing the actual content and its total number.

In summary,archiveFiltersThe returned data of the interface includestotalfield is often displayed as0It is not because there is no content, but because it does not undertake the task of real-time statistics. Its true purpose is as part of the data structure, reserved for future possible expansion, and maintains the interface's simplicity and efficiency in the current version. We need to make use ofarchiveFiltersBuild the filtering interface, then combinearchiveListto get the actual document count under the specific filtering conditions.

Common Questions (FAQ)

Q1:archiveFiltersin the interfacetotalthe field is always0Is it because my website has no content or there is a problem with the configuration?【en】A1: No.archiveFiltersin the interfacetotalfield is often displayed as0It is an AnQin CMS design choice, aiming to provide the basic definition of filtering conditions, rather than the real-time statistics of the number of documents under each option. This is done to ensure the response speed of the interface.This has nothing to do with the correctness of your website content or configuration.

【en】Q2: If I want to display the current number of documents for each filter option (such as "Beijing") on the filter interface, how should I implement it?A2:archiveFiltersThe interface itself does not provide the real-time count for each option. If you need to display such counts on the frontend, you need to combinearchiveListInterface. You can call once for each filter option (such as “Beijing”, “Shanghai”)archiveListinterface, passing the corresponding filter parameters (for example)city=北京and settype=pagearchiveListreturnedtotalTo get the document count under this option, please refer to the field. However, please note that this method may increase the server's request load.

Q3:archiveFiltersReturned by the interface.field_nameWhat is the use of it?A3:field_nameThis is a very critical field, it indicates which parameter name should be used to apply filtering when callingarchiveListthe interface. For example, ifarchiveFiltersa response was returnedfield_nameresponse forcityThe filter, so when the user selects “Beijing”, you should add in thearchiveListrequest parameterscity=北京To obtain the corresponding data. It is the bridge that connects the selection of the filter interface with the actual data query.