When building a website or application with AnQiCMS, we often need to use its provided API interface to retrieve various contents, such as document lists.What kind of data structure will the API return when our query conditions do not match any content?dataandtotalThese two keyword fields are crucial for the correct processing of data.Today, let's delve into how Anqi CMS responds when no matching document is found in the document list.

The API response when there is no result in the document list query

Byarchive/listTaking the interface as an example, this interface is designed to retrieve a document list that meets specific conditions. When you pass in query parameters such ascategoryId/qThe search keyword or custom filtering parameters, and if no documents are matched, the API of Anqi CMS will not return an error status code.On the contrary, it would consider this a successful query, but the result set is empty.

This means, you will seecodethe field is still0indicating that the request was processed successfully. Andmsgthe field is usually an empty string"", or occasionally includes some default prompts that do not affect the logic, but the core idea is: there is no technical error in the request itself.

What we really need to pay attention to isdataField. In this case,datait will not returnnull, but will return aempty array[]. This is in line with common practices in API design,dataAlways maintain its type (here an array), even if the array has no elements. For example, you might receive the following response fragment:

{
  "code": 0,
  "data": [],
  "msg": ""
}

This design allows us to directly traverse the data on the front-end or back-enddataarray; if the length of the array is zero, we know that no documents have been found, and no additional check is neededdataIs itnull.

Then istotalField. According to the document's instructions,totalonly whentype="page"(pagination mode) is selected will it return. Therefore, if your request has settype="page", and no documents are found, thentotalthis field will return0It clearly tells us that although the request was successful, the total number of documents that meet the criteria is zero.

However, if you are using the defaulttype="list"mode, or it has not been explicitly settypeParameter, if no document is found,totalthe field willnot appear in the response. This means, inlistmode, the existence of the document is mainly judged by checkingdataThe array is empty or not.

Suggested handling in actual development.

It is very important to understand this return mechanism. When you call the document list API of Anqi CMS, it is recommended that you first checkcodewhether the field is0Check if the request is successful. Then, fordatafield, directly judge whether the length of its array is0to know if there is any content. If you usetype="page"for pagination queries, then you cantotalThe total number of entries directly obtained is0information.

It is worth mentioning that this API response pattern of Anqi CMS is consistent in its other list-style interfaces, such as getting the category list (category/list)、标签数据列表 (English)tag/data/list) 甚至订单列表 (English)orders) 等，在没有符合条件的结果时，它们的 (English)data字段也会是一个空数组，而 (English)totalField (if pagination is supported) will be0.

Mastered the standard return format of AnQi CMS in the case of no result query, which can help us write code more robustly and elegantly, avoid unnecessary error judgments, and ensure the stable operation of the website or application and a good user experience.

Common Questions (FAQ)

  1. Q: Why even if the document is not found,codethe field is still0(Success) instead of an error code? A:The API design of AnQi CMS treats "No documents found that match the criteria" as a successful query, merely indicating that the result set is empty, rather than an error occurring in the API service itself. Therefore,code依然表示API请求处理流程是正常的。

  2. Q: Ifdata返回的是一个空数组[]，我应该怎样判断是否有内容？ A:最直接且推荐的方式是检查dataThe length of the array.data.lengthresponse for0It means that nothing was found.

  3. Q:totalWhether the field always returns0? A:Not necessarily.totalThe field will only be returned when you explicitly set ittype="page"Parameters will be paginated in the response. In this case, if the query results are empty,totalit will return0. If not set,type="page"(i.e., using the default),type="list"), it will not be included in the response.totalfield.