From 01f86bbaf551455be9f040ef971fc4bc1e0f78b8 Mon Sep 17 00:00:00 2001
From: Alex Dzeda <alex@e14s.com>
Date: Wed, 3 Apr 2024 09:04:51 -0500
Subject: [PATCH] add best practices section and 429 recommendations

---
 _includes/build/best_practices.html     |  7 ++++++
 _includes/build/best_practices_429.html | 15 ++++++++++++
 build.html                              | 31 +++++++++++++++++++++++++
 3 files changed, 53 insertions(+)
 create mode 100644 _includes/build/best_practices.html
 create mode 100644 _includes/build/best_practices_429.html

diff --git a/_includes/build/best_practices.html b/_includes/build/best_practices.html
new file mode 100644
index 0000000..2611682
--- /dev/null
+++ b/_includes/build/best_practices.html
@@ -0,0 +1,7 @@
+<div>
+    <p>
+        There are many ways to accomplish the same objective within BCDA, and following our list of best practices can ensure optimal performance for all consumers of BCDA. 
+    </p>
+    
+</div>
+    
\ No newline at end of file
diff --git a/_includes/build/best_practices_429.html b/_includes/build/best_practices_429.html
new file mode 100644
index 0000000..04abf62
--- /dev/null
+++ b/_includes/build/best_practices_429.html
@@ -0,0 +1,15 @@
+
+<div>
+    <p>Occasionally, when interacting with BCDA, you might encounter responses with a status code of <code>429 Too Many Requests</code>. This can happen for two main reasons:</p>
+  
+    <p>BCDA assigns 429 response codes based on two independent criteria:</p>
+  
+    <ol>
+      <li>Making too many HTTP requests in a period of time.</li>
+      <li>Attempting to create duplicate jobs.</li>
+    </ol>
+  
+    <p>Regardless of the reason, BCDA will include a <strong>Retry-After</strong> header in its response. It's considered best practice to wait until the period specified in this header has elapsed before making further requests. This ensures your client can adapt without manual intervention, even if the rate-limiting parameters change.</p>
+  
+    <p>Concerning duplicate jobs, BCDA defines them as attempts to recreate a job already marked as "In-Progress". For reference, you can view both existing and past jobs by accessing the job history endpoint at <code>/jobs</code>.</p>
+</div>
\ No newline at end of file
diff --git a/build.html b/build.html
index 04a97f1..0cd2962 100644
--- a/build.html
+++ b/build.html
@@ -116,6 +116,20 @@
             </li>
           </ul> 
         </li>
+
+
+        <li class="ds-c-vertical-nav__item">
+          <a class="ds-c-vertical-nav__label ds-c-vertical-nav__label" href="#bulk-best-practices">
+            Best Practices
+          </a>
+          <ul class="ds-c-vertical-nav__subnav">
+            <li class="ds-c-vertical-nav__subnav">
+              <a class="ds-c-vertical-nav__label ds-c-vertical-nav__label" href="#handling-429-error">
+                Handling 429 status codes
+              </a>
+            </li>
+          </ul>
+        </li>
       </ul>
     </aside>
     <!-- Table of Contents END -->
@@ -266,6 +280,23 @@ <h2>
           </div>
         </div>        
       </div>
+
+      <div id="bulk-best-practices" class="guide-content">
+        <h1>
+          Best Practices for Utilizing BCDA
+        </h1>
+        <div class="ds-u-font-size--base ">
+          {% include build/best_practices.html %}
+        </div>
+        <div id="handling-429-error">
+          <h2>
+            Handling 429 status codes
+          </h2>
+          <div class="ds-u-font-size--base">
+            {% include build/best_practices_429.html %}
+          </div>
+        </div>
+      </div>
     </main>
   </div>
 </div>
\ No newline at end of file