From d24d53a3127e04b24f702079e3a513d0ccfc8e65 Mon Sep 17 00:00:00 2001
From: Oguz Kocer <oguz.kocer@automattic.com>
Date: Sat, 25 Nov 2023 11:25:39 -0500
Subject: [PATCH] Initial design for Post Request scaffolding

---
 wordpress_api/src/lib.rs            | 15 ++++++++
 wordpress_api/src/posts.rs          | 51 ++++++++++++++++++++++++++
 wordpress_api/src/wordpress_api.udl | 57 +++++++++++++++++++++++++++++
 3 files changed, 123 insertions(+)
 create mode 100644 wordpress_api/src/posts.rs

diff --git a/wordpress_api/src/lib.rs b/wordpress_api/src/lib.rs
index b94e8e41b..414c29dcd 100644
--- a/wordpress_api/src/lib.rs
+++ b/wordpress_api/src/lib.rs
@@ -1,3 +1,10 @@
+#![allow(dead_code)]
+use std::sync::Arc;
+
+use posts::*;
+
+mod posts;
+
 pub fn add_custom(left: i32, right: i32) -> i32 {
     left + right
 }
@@ -10,6 +17,14 @@ pub fn panic_from_rust() {
     std::fs::read_to_string("doesnt_exist.txt").unwrap();
 }
 
+struct RequestBuilder {}
+
+impl RequestBuilder {
+    fn posts(&self) -> Arc<PostsRequestBuilder> {
+        Arc::new(PostsRequestBuilder {})
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/wordpress_api/src/posts.rs b/wordpress_api/src/posts.rs
new file mode 100644
index 000000000..1ba1a9744
--- /dev/null
+++ b/wordpress_api/src/posts.rs
@@ -0,0 +1,51 @@
+pub struct PostsRequestBuilder {}
+
+impl PostsRequestBuilder {
+    pub fn list(&self, params: Option<PostsListParams>) -> PostsRequest {
+        todo!()
+    }
+
+    pub fn create(&self, params: Option<PostsCreateParams>) -> PostsRequest {
+        todo!()
+    }
+
+    pub fn retrieve(&self, post_id: u32, params: Option<PostsRetrieveParams>) -> PostsRequest {
+        todo!()
+    }
+
+    pub fn update(&self, post_id: u32, params: Option<PostsUpdateParams>) -> PostsRequest {
+        todo!()
+    }
+
+    pub fn delete(&self, post_id: u32, params: Option<PostsDeleteParams>) -> PostsRequest {
+        todo!()
+    }
+}
+
+pub struct PostsListParams {
+    pub page: Option<u32>,
+    pub per_page: Option<u32>,
+}
+
+pub struct PostsCreateParams {
+    pub title: Option<String>,
+    pub content: Option<String>,
+}
+
+pub struct PostsRetrieveParams {
+    pub password: Option<String>,
+}
+
+pub struct PostsUpdateParams {
+    pub title: Option<String>,
+    pub content: Option<String>,
+}
+
+pub struct PostsDeleteParams {
+    pub force: Option<bool>,
+}
+
+pub struct PostsRequest {
+    pub endpoint: String,
+    pub params: Option<String>,
+}
diff --git a/wordpress_api/src/wordpress_api.udl b/wordpress_api/src/wordpress_api.udl
index 85815f8ab..b3fcb9b66 100644
--- a/wordpress_api/src/wordpress_api.udl
+++ b/wordpress_api/src/wordpress_api.udl
@@ -1,5 +1,62 @@
+// These are test functions that we are keeping while we figure out the design in case
+// we need them for further testing.
 namespace wordpress_api {
   i32 add_custom(i32 a, i32 b);
   string combine_strings(string a, string b);
   void panic_from_rust();
 };
+
+interface RequestBuilder {
+  PostsRequestBuilder posts();
+};
+
+// https://developer.wordpress.org/rest-api/reference/posts/
+// TODO: The schema and some of the action arguments for `/posts` endpoint has the notion of `context`.
+// This is an `enum` value, but it can only contain partial values per field.
+// This is an important design element to get right, because it's a common pattern for the API.
+//
+// IMPORTANT: This design does not include error handling yet!
+interface PostsRequestBuilder {
+  PostsRequest list(PostsListParams? params);
+  PostsRequest create(PostsCreateParams? params);
+  PostsRequest retrieve(u32 post_id, PostsRetrieveParams? params);
+  PostsRequest update(u32 post_id, PostsUpdateParams? params);
+  PostsRequest delete(u32 post_id, PostsDeleteParams? params);
+};
+
+// If we can represent a trait relationship in UDL, we could use a common Request trait
+// However, we'd still want a specific `PostsRequest` type so that we can have a strongly typed
+// return value for it.
+//
+// The reason we can use a `PostsRequest` type and not need a more specific type such as
+// `PostsListRequest` is because the API documentation states that the return value for
+// all `/posts` requests have the same schema: https://developer.wordpress.org/rest-api/reference/posts/#schema
+// If this is not the case, we'll need more specific types.
+dictionary PostsRequest {
+  string endpoint;
+  string? params;
+};
+
+// We should check if it's possible to use the same params for update & create
+dictionary PostsCreateParams {
+  string? title;
+  string? content;
+};
+
+dictionary PostsListParams {
+  u32? page;
+  u32? per_page;
+};
+
+dictionary PostsRetrieveParams {
+  string? password;
+};
+
+dictionary PostsUpdateParams {
+  string? title;
+  string? content;
+};
+
+dictionary PostsDeleteParams {
+  boolean? force;
+};