From e3b12877925607018e03b66273fd477e35b0b418 Mon Sep 17 00:00:00 2001 From: Carolina Menezes <60782333+carolinamenezes@users.noreply.github.com> Date: Mon, 29 Jan 2024 18:32:16 -0300 Subject: [PATCH] Update README.md (#83) * Update README.md * Update CHANGELOG.md --- CHANGELOG.md | 4 ++++ docs/README.md | 42 ++++++++++++++++++------------------------ 2 files changed, 22 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 36dd3ef..d58f34c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +### Fixed + +- Min docs improvement + ## [0.2.23] - 2024-01-23 ### Removed diff --git a/docs/README.md b/docs/README.md index 8643f80..ce5ed62 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,3 @@ - - # Service Example A reference app implementing a VTEX IO service with HTTP route handlers. @@ -12,9 +10,7 @@ We also use the [**node-vtex-api**](https://github.com/vtex/node-vtex-api), a VT - Start from `node/index.ts` and follow the comments and imports :) -## Recipes - -### Defining routes on _service.json_ +## Defining routes on _service.json_ ```json { "memory": 256, @@ -31,26 +27,29 @@ We also use the [**node-vtex-api**](https://github.com/vtex/node-vtex-api), a VT } ``` -The `service.json` file that sits on the root of the `node` folder holds informations about this service, like the maximum timeout and number of replicas, what might be discontinued on the future, but also **sets its routes**. +The `service.json` file that sits on the root of the `node` folder holds information about this service, like the maximum timeout and number of replicas, but also sets its routes. -Koa uses the [path-to-regexp](https://github.com/pillarjs/path-to-regexp) format for defining routes and, as seen on the example, we use the `:code` notation for declaring a **route param** named code, in this case. A HTTP request for `https://{{workspace}}--{{account}}.myvtex.com/_v/status/500` will match the route we've defined. +Koa uses the [path-to-regexp](https://github.com/pillarjs/path-to-regexp) format for defining routes and, as seen in the example, we use the `:code` notation for declaring a route param named `code`. An HTTP request for `https://{{workspace}}--{{account}}.myvtex.com/_v/status/500` will match the route we've defined. -For cach _key_ on the `routes` object, there should be a **corresponding entry** on the exported Service object on `node/index.ts`, this will hook your code to a specific route. +For each _key_ on the `routes` object, there should be a corresponding entry on the exported Service object on `node/index.ts`. This will hook your code to a specific route. -### Access Control -You can also provide a `public` option for each route. If `true`, that resource will be reachable for everyone on the internet. If `false`, VTEX credentials will be requested as well. +## Access Control +You can also provide a `public` option for each route. If `true`, that resource will be reachable to everyone on the internet. If `false`, VTEX credentials will be requested as well. -Another way of controlling access to specific routes is using **ReBACs (Resource-based access)**, that supports more robust configuration. You can read more [on this document](https://docs.google.com/document/d/1ZxNHMFIXfXz3BgTN9xyrHL3V5dYz14wivYgQjRBZ6J8/edit#heading=h.z7pad3qd2qw7) (VTEX only). +Another way of controlling access to specific routes is using **ReBACs (Resource-based access)**, which supports a more robust configuration. You can read more [on this document](https://docs.google.com/document/d/1ZxNHMFIXfXz3BgTN9xyrHL3V5dYz14wivYgQjRBZ6J8/edit#heading=h.z7pad3qd2qw7) (VTEX only). -#### Query String +### Query String For `?accepting=query-string`, you **don't need to declare anything**, as any query provided to the URL will already be available for you to use on the code as `ctx.query`, already parsed as an object, or `ctx.queryString`, taken directly from the URL as a string. -#### Route Params +### Route Params Route Params will be available for you to use on the code as `ctx.vtex.params`, already parsed as an object. For a path like `/_v/status/:code`, if you receive the request `/_v/status/200`, `ctx.vtex.params` will return `{ code: '200' }` -#### HTTP methods -When you define a route on the `service.json`, your NodeJS handlers for that route will be triggered **on every HTTP method** (GET, POST, PUT...), so, if you need to handle them separately you need to implement a "sub-router". Fortunately, the _node-vtex-api_ provides a helper function `method`, exported from `@vtex/api`, to accomplish that behaviour. Instead of passing your handlers directly to the corresponding route on `index.ts`, you pass a `method` call passing **an object with the desired method as key and one handler as its corresponding value**. Check this example: +### HTTP methods + +When you define a route on the `service.json`, your NodeJS handlers for that route will be triggered on every HTTP method (GET, POST, PUT...), so if you need to handle them separately, you need to implement a "sub-router". Fortunately, the _node-vtex-api_ provides a helper function `method`, exported from `@vtex/api`, to accomplish that behavior. Instead of passing your handlers directly to the corresponding route on `index.ts`, you pass a `method` call passing an object with the desired method as key and one handler as its corresponding value. + +Check this example: ```typescript import { method } from '@vtex/api' ... @@ -66,9 +65,9 @@ export default new Service({ }) ``` -### Throwing errors +## Throwing errors -When building a HTTP service, we should follow HTTP rules regarding data types, cache, authorization, and status code. Our example app sets a `ctx.status` value that will be used as a HTTP status code return value, but often we also want to give proper information about errors as well. +When building an HTTP service, we should follow HTTP rules regarding data types, cache, authorization, and status codes. Our example app sets a `ctx.status` value that will be used as an HTTP status code return value, but often, we also want to give proper information about errors. The **node-vtex-api** already exports a handful of **custom error classes** that can be used for that purpose, like the `NotFoundError`. You just need to throw them inside one of the route handlers that the appropriate response will be sent to the server. @@ -94,9 +93,9 @@ You can check all the available errors [here](https://github.com/vtex/node-vtex- You can also **create your custom error**, just see how it's done above ;) -### Reading a JSON body +## Reading a JSON body -When writing POST or PUT handlers, for example, often you need to have access to the **request body** that comes as a JSON format, which is not provided directly by the handler function. +When writing POST or PUT handlers, for example, you often need to have access to the **request body** that comes in a JSON format, which is not provided directly by the handler function. For this, you have to use the [co-body](https://www.npmjs.com/package/co-body) package that will parse the request into a readable JSON object, used as below: ```typescript @@ -105,11 +104,6 @@ export async function method(ctx: Context, next: () => Promise) { const body = await json(ctx.req) ``` -### Other example apps - -We use Node services across all VTEX, and there are a lot inspiring examples. If you want to dive deeper on learning about this subject, don't miss those internal apps: [builder-hub](https://github.com/vtex/builder-hub) or [store-sitemap](https://github.com/vtex-apps/store-sitemap) - - ## Testing `@vtex/test-tools` and `@types/jest` should be installed on `./node` package as `devDependencies`.