From 01f86bbaf551455be9f040ef971fc4bc1e0f78b8 Mon Sep 17 00:00:00 2001 From: Alex Dzeda Date: Wed, 3 Apr 2024 09:04:51 -0500 Subject: [PATCH 1/5] 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 @@ +
+

+ 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. +

+ +
+ \ 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 @@ + +
+

Occasionally, when interacting with BCDA, you might encounter responses with a status code of 429 Too Many Requests. This can happen for two main reasons:

+ +

BCDA assigns 429 response codes based on two independent criteria:

+ +
    +
  1. Making too many HTTP requests in a period of time.
    2. +
  2. Attempting to create duplicate jobs.
    3. +
+ +

Regardless of the reason, BCDA will include a Retry-After 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.

+ +

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 /jobs.

+
\ 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 @@ + + +
  • + + Best Practices + + +
    • @@ -266,6 +280,23 @@

    + +
    +

    + Best Practices for Utilizing BCDA +

    +
    + {% include build/best_practices.html %} +
    +
    +

    + Handling 429 status codes +

    +
    + {% include build/best_practices_429.html %} +
    +
    +
    \ No newline at end of file From e59c4944511ffa030a796679b55f897078d1df24 Mon Sep 17 00:00:00 2001 From: Alex Dzeda Date: Wed, 3 Apr 2024 09:53:44 -0500 Subject: [PATCH 2/5] remove duplicate text --- _includes/build/best_practices_429.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_includes/build/best_practices_429.html b/_includes/build/best_practices_429.html index 04abf62..25e7887 100644 --- a/_includes/build/best_practices_429.html +++ b/_includes/build/best_practices_429.html @@ -1,6 +1,6 @@
    -

    Occasionally, when interacting with BCDA, you might encounter responses with a status code of 429 Too Many Requests. This can happen for two main reasons:

    +

    Occasionally, when interacting with BCDA, you might encounter responses with a status code of 429 Too Many Requests.

    BCDA assigns 429 response codes based on two independent criteria:

    From 5e6922f66a7e7821889f254f8ddfbec1d87838b9 Mon Sep 17 00:00:00 2001 From: Alex Dzeda Date: Wed, 3 Apr 2024 09:57:19 -0500 Subject: [PATCH 3/5] update runout reference to 429 handling --- _includes/build/requesting_data_runouts.html | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/_includes/build/requesting_data_runouts.html b/_includes/build/requesting_data_runouts.html index 153fbcf..68bcf20 100644 --- a/_includes/build/requesting_data_runouts.html +++ b/_includes/build/requesting_data_runouts.html @@ -61,9 +61,10 @@

    Start a Job using 'runout' with /Group Explanation

    If the request was successful, a 202 Accepted response code will be returned and the response will include a Content-Location header. The value of the Content-Location header indicates the location to check for job status and outcome. In the example header above, the number 42 in the URL represents the ID of the export job. The claims returned in the job will be filtered to have a serviceDate of 12/31/2020 or before.

    -

    - If you're already requesting data from one endpoint and try to request data from that endpoint again while the first request is processing, you'll receive a 429 Too Many Requests error. -

    +

    + If you're already requesting data from one endpoint and try to request data from that endpoint again while the first request is processing, you'll receive a 429 Too Many Requests error. For guidance on how to handle 429 errors, refer to our best practices. +

    +

    Step 3: Check the job status

    See Step 3: Check the job status in the Request Data section above.

    From 04a3b2b608a9b6751bf833d6ded7b78d82ad96df Mon Sep 17 00:00:00 2001 From: Alex Dzeda Date: Tue, 9 Apr 2024 10:16:18 -0500 Subject: [PATCH 4/5] update content for best practices and 429 guidance --- _includes/build/best_practices.html | 7 +------ _includes/build/best_practices_429.html | 15 ++++----------- build.html | 2 +- 3 files changed, 6 insertions(+), 18 deletions(-) diff --git a/_includes/build/best_practices.html b/_includes/build/best_practices.html index 2611682..094418b 100644 --- a/_includes/build/best_practices.html +++ b/_includes/build/best_practices.html @@ -1,7 +1,2 @@
    -

    - 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. -

    - -
    - \ No newline at end of file +
    \ No newline at end of file diff --git a/_includes/build/best_practices_429.html b/_includes/build/best_practices_429.html index 25e7887..33a8833 100644 --- a/_includes/build/best_practices_429.html +++ b/_includes/build/best_practices_429.html @@ -1,15 +1,8 @@ -
    -

    Occasionally, when interacting with BCDA, you might encounter responses with a status code of 429 Too Many Requests.

    - -

    BCDA assigns 429 response codes based on two independent criteria:

    - +

    A status code of 429 indicates “Too Many Requests.” This can occur due to two reasons:

      -
    1. Making too many HTTP requests in a period of time.
      2. -
    2. Attempting to create duplicate jobs.
      3. +
    3. Making too many HTTP requests within a period of time
      4. +
    4. Trying to recreate jobs already marked as "In-Progress.” For reference, you can view both existing and past jobs using the /jobs endpoint. See Request Jobs History for more details.
    - -

    Regardless of the reason, BCDA will include a Retry-After 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.

    - -

    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 /jobs.

    +

    Regardless of the reason, you will see a Retry-After response in the header. Wait until the period of time specified in the header has passed before making any more requests. This makes sure your client can adapt without manual intervention, even if the rate-limiting parameters change.

    \ No newline at end of file diff --git a/build.html b/build.html index 0cd2962..a536ce2 100644 --- a/build.html +++ b/build.html @@ -283,7 +283,7 @@

    - Best Practices for Utilizing BCDA + Best Practices

    {% include build/best_practices.html %} From 87ec237927c5d3c2edca2d3d40b2767dc9b8480e Mon Sep 17 00:00:00 2001 From: Alex Dzeda Date: Tue, 9 Apr 2024 10:27:47 -0500 Subject: [PATCH 5/5] remove empty page --- _includes/build/best_practices.html | 2 -- build.html | 3 --- 2 files changed, 5 deletions(-) delete mode 100644 _includes/build/best_practices.html diff --git a/_includes/build/best_practices.html b/_includes/build/best_practices.html deleted file mode 100644 index 094418b..0000000 --- a/_includes/build/best_practices.html +++ /dev/null @@ -1,2 +0,0 @@ -
    -
    \ No newline at end of file diff --git a/build.html b/build.html index a536ce2..f6a7118 100644 --- a/build.html +++ b/build.html @@ -285,9 +285,6 @@

    Best Practices

    -
    - {% include build/best_practices.html %} -

    Handling 429 status codes