feat(http): update the documents resource

- Return Documents API resources on `/documents` in an array in the the results field.
- Add limit, offset and total in the response body.
- Rename `attributesToRetrieve` into `fields` (only for the `/documents` endpoints, not for the `/search` ones).
- The `displayedAttributes` settings does not impact anymore the displayed fields returned in the `/documents` endpoints. These settings only impacts the `/search` endpoint.

Fix #2372

meilisearch-http/src/routes/indexes/documents.rs

@@ -13,7 +13,8 @@ use meilisearch_lib::MeiliSearch;
 use mime::Mime;
 use once_cell::sync::Lazy;
 use serde::Deserialize;
-use serde_json::Value;
+use serde_cs::vec::CS;
+use serde_json::{json, Value};
 use tokio::sync::mpsc;
 
 use crate::analytics::Analytics;
@@ -21,11 +22,9 @@ use crate::error::MeilisearchHttpError;
 use crate::extractors::authentication::{policies::*, GuardedData};
 use crate::extractors::payload::Payload;
 use crate::extractors::sequential_extractor::SeqHandler;
+use crate::routes::{fold_star_or, StarOr};
 use crate::task::SummarizedTaskView;
 
-const DEFAULT_RETRIEVE_DOCUMENTS_OFFSET: usize = 0;
-const DEFAULT_RETRIEVE_DOCUMENTS_LIMIT: usize = 20;
-
 static ACCEPTED_CONTENT_TYPE: Lazy<Vec<String>> = Lazy::new(|| {
     vec![
         "application/json".to_string(),
@@ -86,14 +85,24 @@ pub fn configure(cfg: &mut web::ServiceConfig) {
     );
 }
 
+#[derive(Deserialize, Debug)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct GetDocument {
+    fields: Option<CS<StarOr<String>>>,
+}
+
 pub async fn get_document(
     meilisearch: GuardedData<ActionPolicy<{ actions::DOCUMENTS_GET }>, MeiliSearch>,
     path: web::Path<DocumentParam>,
+    params: web::Query<GetDocument>,
 ) -> Result<HttpResponse, ResponseError> {
     let index = path.index_uid.clone();
     let id = path.document_id.clone();
+    let GetDocument { fields } = params.into_inner();
+    let attributes_to_retrieve = fields.map(CS::into_inner).and_then(fold_star_or);
+
     let document = meilisearch
-        .document(index, id, None as Option<Vec<String>>)
+        .document(index, id, attributes_to_retrieve)
         .await?;
     debug!("returns: {:?}", document);
     Ok(HttpResponse::Ok().json(document))
@@ -113,12 +122,16 @@ pub async fn delete_document(
     Ok(HttpResponse::Accepted().json(task))
 }
 
+const PAGINATION_DEFAULT_LIMIT: fn() -> usize = || 20;
+
 #[derive(Deserialize, Debug)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct BrowseQuery {
-    offset: Option<usize>,
-    limit: Option<usize>,
-    attributes_to_retrieve: Option<String>,
+    #[serde(default)]
+    offset: usize,
+    #[serde(default = "PAGINATION_DEFAULT_LIMIT")]
+    limit: usize,
+    fields: Option<CS<StarOr<String>>>,
 }
 
 pub async fn get_all_documents(
@@ -127,27 +140,21 @@ pub async fn get_all_documents(
     params: web::Query<BrowseQuery>,
 ) -> Result<HttpResponse, ResponseError> {
     debug!("called with params: {:?}", params);
-    let attributes_to_retrieve = params.attributes_to_retrieve.as_ref().and_then(|attrs| {
-        let mut names = Vec::new();
-        for name in attrs.split(',').map(String::from) {
-            if name == "*" {
-                return None;
-            }
-            names.push(name);
-        }
-        Some(names)
-    });
+    let BrowseQuery {
+        offset,
+        limit,
+        fields,
+    } = params.into_inner();
+    let attributes_to_retrieve = fields.map(CS::into_inner).and_then(fold_star_or);
 
-    let documents = meilisearch
-        .documents(
-            path.into_inner(),
-            params.offset.unwrap_or(DEFAULT_RETRIEVE_DOCUMENTS_OFFSET),
-            params.limit.unwrap_or(DEFAULT_RETRIEVE_DOCUMENTS_LIMIT),
-            attributes_to_retrieve,
-        )
+    let (total, documents) = meilisearch
+        .documents(path.into_inner(), offset, limit, attributes_to_retrieve)
         .await?;
+
     debug!("returns: {:?}", documents);
-    Ok(HttpResponse::Ok().json(documents))
+    Ok(HttpResponse::Ok().json(json!(
+        { "limit": limit, "offset": offset, "total": total, "results": documents }
+    )))
 }
 
 #[derive(Deserialize, Debug)]

meilisearch-http/src/routes/mod.rs

@@ -1,3 +1,5 @@
+use std::str::FromStr;
+
 use actix_web::{web, HttpResponse};
 use log::debug;
 use serde::{Deserialize, Serialize};
@@ -24,6 +26,38 @@ pub fn configure(cfg: &mut web::ServiceConfig) {
         .service(web::scope("/indexes").configure(indexes::configure));
 }
 
+/// A type that tries to match either a star (*) or
+/// any other thing that implements `FromStr`.
+#[derive(Debug)]
+pub enum StarOr<T> {
+    Star,
+    Other(T),
+}
+
+impl<T: FromStr> FromStr for StarOr<T> {
+    type Err = T::Err;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        if s.trim() == "*" {
+            Ok(StarOr::Star)
+        } else {
+            T::from_str(s).map(StarOr::Other)
+        }
+    }
+}
+
+/// Extracts the raw values from the `StarOr` types and
+/// return None if a `StarOr::Star` is encountered.
+pub fn fold_star_or<T>(content: impl IntoIterator<Item = StarOr<T>>) -> Option<Vec<T>> {
+    content
+        .into_iter()
+        .map(|value| match value {
+            StarOr::Star => None,
+            StarOr::Other(val) => Some(val),
+        })
+        .collect()
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[allow(clippy::large_enum_variant)]
 #[serde(tag = "name")]

meilisearch-http/src/routes/tasks.rs

@@ -6,13 +6,14 @@ use meilisearch_lib::{IndexUid, MeiliSearch};
 use serde::Deserialize;
 use serde_cs::vec::CS;
 use serde_json::json;
-use std::str::FromStr;
 
 use crate::analytics::Analytics;
 use crate::extractors::authentication::{policies::*, GuardedData};
 use crate::extractors::sequential_extractor::SeqHandler;
 use crate::task::{TaskListView, TaskStatus, TaskType, TaskView};
 
+use super::{fold_star_or, StarOr};
+
 pub fn configure(cfg: &mut web::ServiceConfig) {
     cfg.service(web::resource("").route(web::get().to(SeqHandler(get_tasks))))
         .service(web::resource("/{task_id}").route(web::get().to(SeqHandler(get_task))));
@@ -27,40 +28,6 @@ pub struct TaskFilterQuery {
     index_uid: Option<CS<StarOr<IndexUid>>>,
 }
 
-/// A type that tries to match either a star (*) or
-/// any other thing that implements `FromStr`.
-#[derive(Debug)]
-enum StarOr<T> {
-    Star,
-    Other(T),
-}
-
-impl<T: FromStr> FromStr for StarOr<T> {
-    type Err = T::Err;
-
-    fn from_str(s: &str) -> Result<Self, Self::Err> {
-        if s.trim() == "*" {
-            Ok(StarOr::Star)
-        } else {
-            T::from_str(s).map(StarOr::Other)
-        }
-    }
-}
-
-/// Extracts the raw values from the `StarOr` types and
-/// return None if a `StarOr::Star` is encountered.
-fn fold_star_or<T>(content: Vec<StarOr<T>>) -> Option<Vec<T>> {
-    content
-        .into_iter()
-        .fold(Some(Vec::new()), |acc, val| match (acc, val) {
-            (None, _) | (_, StarOr::Star) => None,
-            (Some(mut acc), StarOr::Other(uid)) => {
-                acc.push(uid);
-                Some(acc)
-            }
-        })
-}
-
 #[rustfmt::skip]
 fn task_type_matches_content(type_: &TaskType, content: &TaskContent) -> bool {
     matches!((type_, content),