From 4156d6135c22050a6c8c9b8014c1d251b9f1c305 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 12:58:10 -0500 Subject: [PATCH 01/14] use Create/Delete and Add/Remove verbs --- docs/API.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/API.md b/docs/API.md index 147ba33537a1..f7ae6bf2fcaa 100644 --- a/docs/API.md +++ b/docs/API.md @@ -49,5 +49,7 @@ For example: Accessing the data for a chat report will return the data if the re - Nouns can be optional eg. `SignIn` - Verbs should be unique and indicate the user's action (as perceived by the user). eg. `Request`, `Open`, `Accept`, `Pay` - If a unique verb cannot be used, then use only the standard verbs: `Update`, `Add`, `Delete` + - Use Create/Delete to create or destroy the only copy of data + - Use Add/Remove when we're just dealing with the copy of data - Names must NOT include names of parameters eg. Bad: `SignInWithPasswordOr2FA` Good: `SignIn` - Names must NOT reveal backend implementation details that the user does not know about eg. `AddVBBA` (users don't know what a VBBA is - verified business bank account) Good: `AddBankAccount` From dc333743c3ee18f26fe3e6f7f0a4ed963514560c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 13:06:02 -0500 Subject: [PATCH 02/14] avoid word Page or View and instructions for deep links --- docs/API.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/API.md b/docs/API.md index f7ae6bf2fcaa..e6cd16a651e1 100644 --- a/docs/API.md +++ b/docs/API.md @@ -52,4 +52,6 @@ For example: Accessing the data for a chat report will return the data if the re - Use Create/Delete to create or destroy the only copy of data - Use Add/Remove when we're just dealing with the copy of data - Names must NOT include names of parameters eg. Bad: `SignInWithPasswordOr2FA` Good: `SignIn` +- Names must NOT the word Page or View, eg. Bad: `OpenReportPage` Good: `OpenReport` - Names must NOT reveal backend implementation details that the user does not know about eg. `AddVBBA` (users don't know what a VBBA is - verified business bank account) Good: `AddBankAccount` +- For deep links like `StartAppWhileSignedInAndOpenWorkspace`, create separate commands for each specific scenario like `StartAppWhileSignedIn` and `OpenWorkspace`, where both requests will be triggered in parallel. From 096644ddff403b649402cec0142c8c0c85bc5ef2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 13:17:03 -0500 Subject: [PATCH 03/14] creating data needs to be flawlessly fast --- docs/API.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/API.md b/docs/API.md index e6cd16a651e1..76343325d615 100644 --- a/docs/API.md +++ b/docs/API.md @@ -6,6 +6,8 @@ These are best practices related to the current API used for App. This does not - There should be no client-side handling that is unique to any API call. - Data is pushed to the client and put straight into Onyx by low-level libraries. - Clients should be kept up-to-date with many small incremental changes to data. +- Creating data needs to be flawlessly fast on every connection (offline, slow 3G, etc). + ## Response Handling When the web server responds to an API call the response is sent to the server in one of two ways. 1. **HTTPS Response** - Data that is returned with the HTTPS response is only sent to the client that initiated the request. From 5a766d0e6bd1b36cb0668c5a0d1b4052732555c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 13:52:28 -0500 Subject: [PATCH 04/14] add point about random string IDs for new objects --- docs/API.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/API.md b/docs/API.md index 76343325d615..8fda47bfd1d6 100644 --- a/docs/API.md +++ b/docs/API.md @@ -7,6 +7,8 @@ These are best practices related to the current API used for App. This does not - Data is pushed to the client and put straight into Onyx by low-level libraries. - Clients should be kept up-to-date with many small incremental changes to data. - Creating data needs to be flawlessly fast on every connection (offline, slow 3G, etc). +- For new objects created from the client (reports, reportActions, policies) we're going to generate a random string ID immediately on the client, rather than needing to wait for the server to give us an ID for the created object. + ## Response Handling When the web server responds to an API call the response is sent to the server in one of two ways. @@ -57,3 +59,5 @@ For example: Accessing the data for a chat report will return the data if the re - Names must NOT the word Page or View, eg. Bad: `OpenReportPage` Good: `OpenReport` - Names must NOT reveal backend implementation details that the user does not know about eg. `AddVBBA` (users don't know what a VBBA is - verified business bank account) Good: `AddBankAccount` - For deep links like `StartAppWhileSignedInAndOpenWorkspace`, create separate commands for each specific scenario like `StartAppWhileSignedIn` and `OpenWorkspace`, where both requests will be triggered in parallel. + +## \ No newline at end of file From 5e8376cfdfe9513864b61b4cd71e77a5e762faf3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 14:52:12 -0500 Subject: [PATCH 05/14] add FAQ section --- docs/API.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/API.md b/docs/API.md index 8fda47bfd1d6..f9de0ad558ad 100644 --- a/docs/API.md +++ b/docs/API.md @@ -9,7 +9,6 @@ These are best practices related to the current API used for App. This does not - Creating data needs to be flawlessly fast on every connection (offline, slow 3G, etc). - For new objects created from the client (reports, reportActions, policies) we're going to generate a random string ID immediately on the client, rather than needing to wait for the server to give us an ID for the created object. - ## Response Handling When the web server responds to an API call the response is sent to the server in one of two ways. 1. **HTTPS Response** - Data that is returned with the HTTPS response is only sent to the client that initiated the request. @@ -60,4 +59,11 @@ For example: Accessing the data for a chat report will return the data if the re - Names must NOT reveal backend implementation details that the user does not know about eg. `AddVBBA` (users don't know what a VBBA is - verified business bank account) Good: `AddBankAccount` - For deep links like `StartAppWhileSignedInAndOpenWorkspace`, create separate commands for each specific scenario like `StartAppWhileSignedIn` and `OpenWorkspace`, where both requests will be triggered in parallel. -## \ No newline at end of file +## FAQ +Q: How should error messages be persisted to Onyx? +A:- The API layer Pusher onyxData should set specific error messages. + - In cases where the API does not set an error, a generic error message can be set in the API.write onyxData `failureData` block. + - Previous errors should be cleared by local onyxData when a new request is made + +Q: How should we remove local data from the store if the data no longer exist in the server? eg. local policy data for policies the user is no longer a member of. +A: Use Onyx.set(key, null) for each data (eg. policy) not found in the server. \ No newline at end of file From 69cef10a93aebd48531630f759470d05330ae54f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 15:01:27 -0500 Subject: [PATCH 06/14] add another point to the Philosophy section --- docs/API.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/API.md b/docs/API.md index f9de0ad558ad..d8fad4b094ab 100644 --- a/docs/API.md +++ b/docs/API.md @@ -8,6 +8,7 @@ These are best practices related to the current API used for App. This does not - Clients should be kept up-to-date with many small incremental changes to data. - Creating data needs to be flawlessly fast on every connection (offline, slow 3G, etc). - For new objects created from the client (reports, reportActions, policies) we're going to generate a random string ID immediately on the client, rather than needing to wait for the server to give us an ID for the created object. +- Every new command added should be done right the first time (following the correct pattern and not worrying about unblocking a newsletter initiative quickly). ## Response Handling When the web server responds to an API call the response is sent to the server in one of two ways. From 328e566174e6d6a26f91ff9e4be3158b42bcd476 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 16:51:26 -0500 Subject: [PATCH 07/14] remove outdated guidance --- docs/API.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/API.md b/docs/API.md index d8fad4b094ab..a5af30b3f7fa 100644 --- a/docs/API.md +++ b/docs/API.md @@ -53,8 +53,6 @@ For example: Accessing the data for a chat report will return the data if the re - Nouns can be optional eg. `SignIn` - Verbs should be unique and indicate the user's action (as perceived by the user). eg. `Request`, `Open`, `Accept`, `Pay` - If a unique verb cannot be used, then use only the standard verbs: `Update`, `Add`, `Delete` - - Use Create/Delete to create or destroy the only copy of data - - Use Add/Remove when we're just dealing with the copy of data - Names must NOT include names of parameters eg. Bad: `SignInWithPasswordOr2FA` Good: `SignIn` - Names must NOT the word Page or View, eg. Bad: `OpenReportPage` Good: `OpenReport` - Names must NOT reveal backend implementation details that the user does not know about eg. `AddVBBA` (users don't know what a VBBA is - verified business bank account) Good: `AddBankAccount` From b6a227c03b2a463e3205b0258b5d8ae2a579205f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 16:58:45 -0500 Subject: [PATCH 08/14] update point about creating data optimistically --- docs/API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/API.md b/docs/API.md index a5af30b3f7fa..8e72e5ebc386 100644 --- a/docs/API.md +++ b/docs/API.md @@ -6,7 +6,7 @@ These are best practices related to the current API used for App. This does not - There should be no client-side handling that is unique to any API call. - Data is pushed to the client and put straight into Onyx by low-level libraries. - Clients should be kept up-to-date with many small incremental changes to data. -- Creating data needs to be flawlessly fast on every connection (offline, slow 3G, etc). +- Creating data needs to be optimistic on every connection (offline, slow 3G, etc), eg. `RequestMoney` or `SplitBill` should work without waiting for a server response. - For new objects created from the client (reports, reportActions, policies) we're going to generate a random string ID immediately on the client, rather than needing to wait for the server to give us an ID for the created object. - Every new command added should be done right the first time (following the correct pattern and not worrying about unblocking a newsletter initiative quickly). From 02ca396f27d89283f4e7c9c993e40d238c3bca29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 17:03:55 -0500 Subject: [PATCH 09/14] add supplementary comment to random ID point --- docs/API.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/API.md b/docs/API.md index 8e72e5ebc386..6c26e621360f 100644 --- a/docs/API.md +++ b/docs/API.md @@ -8,6 +8,7 @@ These are best practices related to the current API used for App. This does not - Clients should be kept up-to-date with many small incremental changes to data. - Creating data needs to be optimistic on every connection (offline, slow 3G, etc), eg. `RequestMoney` or `SplitBill` should work without waiting for a server response. - For new objects created from the client (reports, reportActions, policies) we're going to generate a random string ID immediately on the client, rather than needing to wait for the server to give us an ID for the created object. + - This client-generated ID will become the primary key for that record in the database. This will provide more offline functionality than was previously possible. - Every new command added should be done right the first time (following the correct pattern and not worrying about unblocking a newsletter initiative quickly). ## Response Handling From c39ff82839e7e91c2356fb46868bc105c4d3db31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 17:09:14 -0500 Subject: [PATCH 10/14] use another heading level for FAQ --- docs/API.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/API.md b/docs/API.md index 6c26e621360f..36147dc9e065 100644 --- a/docs/API.md +++ b/docs/API.md @@ -60,10 +60,13 @@ For example: Accessing the data for a chat report will return the data if the re - For deep links like `StartAppWhileSignedInAndOpenWorkspace`, create separate commands for each specific scenario like `StartAppWhileSignedIn` and `OpenWorkspace`, where both requests will be triggered in parallel. ## FAQ -Q: How should error messages be persisted to Onyx? -A:- The API layer Pusher onyxData should set specific error messages. - - In cases where the API does not set an error, a generic error message can be set in the API.write onyxData `failureData` block. - - Previous errors should be cleared by local onyxData when a new request is made -Q: How should we remove local data from the store if the data no longer exist in the server? eg. local policy data for policies the user is no longer a member of. -A: Use Onyx.set(key, null) for each data (eg. policy) not found in the server. \ No newline at end of file +### How should error messages be persisted to Onyx? + +- The API layer Pusher onyxData should set specific error messages. +- In cases where the API does not set an error, a generic error message can be set in the API.write onyxData `failureData` block. +- Previous errors should be cleared by local onyxData when a new request is made + +### How should we remove local data from the store if the data no longer exist in the server? eg. local policy data for policies the user is no longer a member of. + +Use Onyx.set(key, null) for each data (eg. policy) not found in the server. \ No newline at end of file From 654aa87b1bf427bdc81878f828cebb90b6e44d30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 17:11:52 -0500 Subject: [PATCH 11/14] removing point --- docs/API.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/API.md b/docs/API.md index 36147dc9e065..1a6d0c267f21 100644 --- a/docs/API.md +++ b/docs/API.md @@ -9,7 +9,6 @@ These are best practices related to the current API used for App. This does not - Creating data needs to be optimistic on every connection (offline, slow 3G, etc), eg. `RequestMoney` or `SplitBill` should work without waiting for a server response. - For new objects created from the client (reports, reportActions, policies) we're going to generate a random string ID immediately on the client, rather than needing to wait for the server to give us an ID for the created object. - This client-generated ID will become the primary key for that record in the database. This will provide more offline functionality than was previously possible. -- Every new command added should be done right the first time (following the correct pattern and not worrying about unblocking a newsletter initiative quickly). ## Response Handling When the web server responds to an API call the response is sent to the server in one of two ways. From e880e040e7baa22e4975b359ad6ef377ff019cea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Wed, 22 Jun 2022 17:14:09 -0500 Subject: [PATCH 12/14] add suggestions --- docs/API.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/API.md b/docs/API.md index 1a6d0c267f21..d8e67b75a585 100644 --- a/docs/API.md +++ b/docs/API.md @@ -64,8 +64,8 @@ For example: Accessing the data for a chat report will return the data if the re - The API layer Pusher onyxData should set specific error messages. - In cases where the API does not set an error, a generic error message can be set in the API.write onyxData `failureData` block. -- Previous errors should be cleared by local onyxData when a new request is made +- Previous errors should be cleared in the `optimisticData` when a new request is made ### How should we remove local data from the store if the data no longer exist in the server? eg. local policy data for policies the user is no longer a member of. -Use Onyx.set(key, null) for each data (eg. policy) not found in the server. \ No newline at end of file +Use `Onyx.set(key, null)` for each data (eg. policy) not found in the server. \ No newline at end of file From 0e46186f7ef116075013f8fbe4e3727a6a7db4b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Thu, 23 Jun 2022 10:23:27 -0500 Subject: [PATCH 13/14] fix typo Co-authored-by: Amy Evans --- docs/API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/API.md b/docs/API.md index d8e67b75a585..725a5c8d07e9 100644 --- a/docs/API.md +++ b/docs/API.md @@ -54,7 +54,7 @@ For example: Accessing the data for a chat report will return the data if the re - Verbs should be unique and indicate the user's action (as perceived by the user). eg. `Request`, `Open`, `Accept`, `Pay` - If a unique verb cannot be used, then use only the standard verbs: `Update`, `Add`, `Delete` - Names must NOT include names of parameters eg. Bad: `SignInWithPasswordOr2FA` Good: `SignIn` -- Names must NOT the word Page or View, eg. Bad: `OpenReportPage` Good: `OpenReport` +- Names must NOT include the word Page or View, eg. Bad: `OpenReportPage` Good: `OpenReport` - Names must NOT reveal backend implementation details that the user does not know about eg. `AddVBBA` (users don't know what a VBBA is - verified business bank account) Good: `AddBankAccount` - For deep links like `StartAppWhileSignedInAndOpenWorkspace`, create separate commands for each specific scenario like `StartAppWhileSignedIn` and `OpenWorkspace`, where both requests will be triggered in parallel. From f0813b45889dc96a560dc4a770bd43c6758826a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Ch=C3=A1vez?= Date: Fri, 24 Jun 2022 07:29:23 -0500 Subject: [PATCH 14/14] add "onyxData." for consistency --- docs/API.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/API.md b/docs/API.md index 725a5c8d07e9..08a1389f62f7 100644 --- a/docs/API.md +++ b/docs/API.md @@ -63,8 +63,8 @@ For example: Accessing the data for a chat report will return the data if the re ### How should error messages be persisted to Onyx? - The API layer Pusher onyxData should set specific error messages. -- In cases where the API does not set an error, a generic error message can be set in the API.write onyxData `failureData` block. -- Previous errors should be cleared in the `optimisticData` when a new request is made +- In cases where the API does not set an error, a generic error message can be set in the API.write parameter `onyxData.failureData`. +- Previous errors should be cleared in the `onyxData.optimisticData` when a new request is made. ### How should we remove local data from the store if the data no longer exist in the server? eg. local policy data for policies the user is no longer a member of.