dfinity · nathanosdev · Dec 19, 2024
@@ -1,7 +1,5 @@
 # Serving static assets over HTTP
 
-## Overview
-
 This guide walks through an example project that demonstrates how to create a canister that can serve certified static assets (HTML, CSS, JS) over HTTP. The example project presents a very simple single-page JavaScript application. Assets are embedded into the canister when it is compiled.
 
 This is not a beginner's canister development guide. Many fundamental concepts that a relatively experienced canister developer should already know will be omitted. Concepts specific to asset certification will be called out here and can help to understand the [full code example](https://github.com/dfinity/response-verification/tree/main/examples/http-certification/assets).
@@ -269,7 +267,7 @@ fn certify_all_assets() {
 
 ## Serving assets
 
-The `serve_asset` function is responsible for serving assets. It uses the `serve_asset` function from the `AssetRouter` to serve the assets. This function returns an `HttpResponse` that can be returned to the caller.
+The `serve_asset` function from the `AssetRouter` is responsible for serving assets. This function returns an `HttpResponse` that can be returned to the caller.
 
 ```rust
 fn serve_asset(req: &HttpRequest) -> HttpResponse<'static> {
@@ -342,7 +340,9 @@ fn serve_metrics() -> HttpResponse<'static> {
 
 ## Testing the canister
 
-To test the canister, you can use the `dfx` command-line tool. First, run DFX:
+This example uses a canister called `http_certification_assets_backend`.
+
+To test the canister, you can use [`dfx`](https://internetcomputer.org/docs/current/developer-docs/getting-started/install) to start a local instance of the replica:
 
 ```shell
 dfx start --background --clean

@@ -1,7 +1,5 @@
 # Serving static assets over HTTP (custom)
 
-## Overview
-
 This guide walks through an example project that demonstrates how to create a canister that can serve certified static assets (HTML, CSS, JS) over HTTP. The example project presents a very simple single-page JavaScript application. Assets are embedded into the canister when it is compiled.
 
 This is not a beginner's canister development guide. Many fundamental concepts that a relatively experienced canister developer should already know will be omitted. Concepts specific to HTTP Certification will be called out here and can help to understand the [full code example](https://github.com/dfinity/response-verification/tree/main/examples/http-certification/custom-assets).
@@ -76,9 +74,9 @@ fn post_upgrade() {
 }
 ```
 
-## CEL Expressions
+## CEL expressions
 
-The CEL expression definition is simpler in the case of assets compared to the [JSON API example](https://internetcomputer.org/docs/current/developer-docs/http-compatible-canisters/serving-json-over-http) as the same CEL expression is used for every asset, including the fallback response.
+The CEL expression definition is simpler in the case of assets compared to the [JSON API example](https://internetcomputer.org/docs/current/developer-docs/http-compatible-canisters/serving-json-over-http) as the same CEL expression is used for every asset including the fallback response.
 
 ```rust
 lazy_static! {
@@ -199,7 +197,7 @@ fn certify_asset_response(
 }
 ```
 
-The next function to look at is another reusable function to certify an asset with a specific encoding. This function will check for a file with an additional file extension matching the requested encoding in the statically included asset directory.
+Next is a reusable function to certify an asset with a specific encoding. This function will check for a file with an additional file extension matching the requested encoding in the statically included asset directory.
 
 For example, when certifying `index.html` with `gzip` encoding, this function will check for `index.html.gzip`. If the encoded asset exists, then it is certified using a procedure similar to the previously defined `certify_asset_response` function. The primary difference in this function is where the encoded asset response is stored.
 
@@ -550,7 +548,9 @@ fn http_request(req: HttpRequest) -> HttpResponse {
 
 ## Testing the canister
 
-To test the canister, you can use the `dfx` command-line tool. First, run DFX:
+This example uses a canister called `http_certification_custom_assets_backend`.
+
+To test the canister, you can use [`dfx`](https://internetcomputer.org/docs/current/developer-docs/getting-started/install) to start a local instance of the replica:
 
 ```shell
 dfx start --background --clean

@@ -1,7 +1,5 @@
 # Serving JSON over HTTP
 
-## Overview
-
 This guide walks through an example project that demonstrates how to create a canister that can serve certified JSON over HTTP. The example project presents a very simple REST API for creating and listing to-do items. There is no authentication or persistent storage.
 
 This is not a beginner's canister development guide. Many fundamental concepts that a relatively experienced canister developer should already know will be omitted. Concepts specific to HTTP certification will be called out here and can help to understand the [full code example](https://github.com/dfinity/response-verification/tree/main/examples/http-certification/json-api).
@@ -42,7 +40,7 @@ fn post_upgrade() {
 
 CEL expressions only need to be set up once and can then be reused until the next canister upgrade. Responses can also be set up once and reused. If the response is static and will not change throughout the canister's lifetime, then it only needs to be certified once. If the response can change, however, then it will need to be re-certified every time it changes.
 
-`DefaultResponseOnlyCelExpression` is used when only the response is to be certified. If the request is also to be certified, then `DefaultFullCelExpression` should be used. Alternatively, the higher-level `DefaultCelExpression` can hold any type of CEL expression using the "Default" scheme. In the future, there may be more schemes, and the higher-level `CelExpression` will be able to hold CEL expressions from those different schemes. It is up to the developers to decide how they want to store and organize their CEL expressions.
+`DefaultResponseOnlyCelExpression` is used when only the response is to be certified. If the request is also to be certified, then `DefaultFullCelExpression` should be used. Alternatively, the higher-level `DefaultCelExpression` can hold any type of CEL expression using the "Default" scheme. In the future, there may be more schemes and the higher-level `CelExpression` will be able to hold CEL expressions from those different schemes. It is up to the developers to decide how they want to store and organize their CEL expressions.
 
 In this example, there are two different CEL expressions used, a "full" CEL expression and a "response-only" CEL expression. The "full" CEL expression is used for the certified "todos" and the "response-only" CEL expression for the "Not found" response. For more information on defining CEL expressions, see the relevant section in the [`ic-http-certification` docs](https://docs.rs/ic-http-certification/latest/ic_http_certification/#defining-cel-expressions).
 
@@ -83,7 +81,7 @@ lazy_static! {
 }
 ```
 
-## Response Headers
+## Response headers
 
 The security headers added to responses are based on the [OWASP Secure Headers project](https://owasp.org/www-project-secure-headers/index.html).
 
@@ -380,7 +378,7 @@ fn upgrade_to_update_call_handler(
 
 Upgrading to an `update` call will instruct the HTTP gateway to remake the request as an [`update` call](https://internetcomputer.org/docs/current/references/ic-interface-spec/#http-call). As an update call, the response to this request does not need to be certified. Since the canister's state has changed, however, the static `query` call responses will need to be re-certified. The same functions that certified these responses in the first place can be reused to achieve this.
 
-For creating todo items:
+For creating to-do items:
 
 ```rust
 fn create_todo_item_handler(req: &HttpRequest, _params: &Params) -> HttpResponse<'static> {
@@ -411,7 +409,7 @@ fn create_todo_item_handler(req: &HttpRequest, _params: &Params) -> HttpResponse
 }
 ```
 
-For updating todo items:
+For updating to-do items:
 
 ```rust
 fn update_todo_item_handler(req: &HttpRequest, params: &Params) -> HttpResponse<'static> {
@@ -437,7 +435,7 @@ fn update_todo_item_handler(req: &HttpRequest, params: &Params) -> HttpResponse<
 }
 ```
 
-And, finally, for deleting todo items:
+And, finally, for deleting to-do items:
 
 ```rust
 fn delete_todo_item_handler(_req: &HttpRequest, params: &Params) -> HttpResponse<'static> {
@@ -524,7 +522,9 @@ fn insert_update_route(method: &str, path: &str, route_handler: RouteHandler) {
 
 ## Testing the canister
 
-To test the canister, you can use the `dfx` command-line tool. First, run DFX:
+This example uses a canister called `http_certification_json_api_backend`.
+
+To test the canister, you can use [`dfx`](https://internetcomputer.org/docs/current/developer-docs/getting-started/install) to start a local instance of the replica:
 
 ```shell
 dfx start --background --clean
@@ -533,18 +533,18 @@ dfx start --background --clean
 Then, deploy the canister:
 
 ```shell
-dfx deploy
+dfx deploy http_certification_json_api_backend
 ```
 
-To fetch TODO items:
+To fetch to-do items:
 
 ```shell
 curl -s \
     "http://$(dfx canister id http_certification_json_api_backend).localhost:$(dfx info webserver-port)/todos" \
     --resolve "$(dfx canister id http_certification_json_api_backend).localhost:$(dfx info webserver-port):127.0.0.1" | jq
 ```
 
-To add a TODO item:
+To add a to-do item:
 
 ```shell
 curl -s -X POST \
@@ -554,7 +554,7 @@ curl -s -X POST \
     -d '{ "title": "Learn Motoko" }' | jq
 ```
 
-To update a TODO item:
+To update a to-do item:
 
 ```shell
 curl -s -X PATCH \
@@ -564,7 +564,7 @@ curl -s -X PATCH \
     -d '{ "completed": true }' | jq
 ```
 
-To delete a TODO item:
+To delete a to-do item:
 
 ```shell
 curl -s -X DELETE \

@@ -1,16 +1,14 @@
 # Skipping certification for HTTP responses
 
-## Overview
-
 This guide walks through an example project that demonstrates how to skip HTTP certification for all possible responses from a canister.
 
-WARNING!!! This means that a malicious replica can return whatever data it wants in response to requests directed towards the canister. Think carefully about whether or not this is the right fit for the canister. If certification should only be skipped for certain paths, then check out the ["Serving static assets over HTTP"](https://internetcomputer.org/docs/current/developer-docs/web-apps/http-compatible-canisters/serving-static-assets-over-http) guide where this approach is covered in more detail.
+**WARNING** This means that a malicious replica can return whatever data it wants in response to requests directed towards the canister. Think carefully about whether or not this is the right fit for the canister. If certification should only be skipped for certain paths, then check out the ["Serving static assets over HTTP"](https://internetcomputer.org/docs/current/developer-docs/web-apps/http-compatible-canisters/serving-static-assets-over-http) guide where this approach is covered in more detail.
 
-This is not a beginner's canister development guide. Many fundamental concepts that a relatively experienced canister developer should already know will be omitted. Concepts specific to HTTP Certification will be called out here and can help to understand the [full code example](https://github.com/dfinity/response-verification/tree/main/examples/http-certification/skip-certification).
+This is not a beginner's canister development guide. Many fundamental concepts that a relatively experienced canister developer should already know will be omitted. Concepts specific to HTTP certification will be called out here and can help to understand the [full code example](https://github.com/dfinity/response-verification/tree/main/examples/http-certification/skip-certification).
 
 ## Prerequisites
 
-This is a relatively simple guide so there's no prerequisites as such, but it's recommended to check out the full certification guides to make sure that certification is not a good fit for your project.
+This is a relatively simple guide, so there are no prerequisites as such, but it's recommended to check out the full certification guides to make sure that certification is not a good fit for your project.
 
 - [x] Complete the ["Serving static assets over HTTP"](https://internetcomputer.org/docs/current/developer-docs/web-apps/http-compatible-canisters/serving-static-assets-over-http) guide.
 - [x] Complete the ["Custom HTTP Canisters"](https://internetcomputer.org/docs/current/developer-docs/http-compatible-canisters/custom-http-canisters) guide.
@@ -28,7 +26,7 @@ use ic_http_certification::utils::skip_certification_certified_data;
 
 #[init]
 fn init() {
-    set_certified_data(&skip_certification_certified_data());
+    set_certified_data(&skip_certification_certified_data());
 }
 ```
 
@@ -42,31 +40,33 @@ use ic_http_certification::utils::add_skip_certification_header;
 
 #[query]
 fn http_request() -> HttpResponse<'static> {
-    let mut response = create_response();
+    let mut response = create_response();
 
-    add_skip_certification_header(data_certificate().unwrap(), &mut response);
+    add_skip_certification_header(data_certificate().unwrap(), &mut response);
 
-    response
+    response
 }
 ```
 
 The call to `data_certificate` returns a certificate that proves the canister's certified data was signed by consensus. This will be included in the header along with all additional information required by the HTTP Gateway to safely skip verification of this response.
 
 ## Testing the canister
 
-Start DFX:
+This example uses a canister called `http_certification_skip_certification_backend`.
+
+To test the canister, you can use [`dfx`](https://internetcomputer.org/docs/current/developer-docs/getting-started/install) to start a local instance of the replica:
 
 ```shell
 dfx start --background --clean
 ```
 
-Deploy the canister:
+Then, deploy the canister:
 
 ```shell
 dfx deploy http_certification_skip_certification_backend
 ```
 
-Make a request to the canister using cURL:
+Make a request to the canister using curl:
 
 ```shell
 curl -s http://localhost:$(dfx info webserver-port)?canisterId=$(dfx canister id http_certification_skip_certification_backend) | jq
@@ -80,7 +80,7 @@ You should see output similar to the following:
 }
 ```
 
-Alternatively, print the URL in the terminal and then open in a browser:
+Alternatively, print the URL in the terminal and then open it in a browser:
 
 ```shell
 echo http://localhost:$(dfx info webserver-port)?canisterId=$(dfx canister id http_certification_skip_certification_backend)