From e0fc68d4c0d3c097121dd897f2af4f9d71e441e6 Mon Sep 17 00:00:00 2001 From: KM Koushik Date: Wed, 22 May 2024 19:43:17 +1000 Subject: [PATCH] Add dcoumentation for API (#18) --- apps/docs/api-reference/introduction.mdx | 24 +++++++++++++ apps/docs/api-reference/openapi.json | 12 +++++++ apps/docs/get-started/nodejs.mdx | 35 +++++++++++++++++++ apps/docs/introduction.mdx | 7 ++++ apps/docs/mint.json | 7 ++-- apps/web/src/server/public-api/api-error.ts | 15 +++----- .../server/public-api/api/emails/get-email.ts | 14 ++++++++ 7 files changed, 100 insertions(+), 14 deletions(-) create mode 100644 apps/docs/get-started/nodejs.mdx diff --git a/apps/docs/api-reference/introduction.mdx b/apps/docs/api-reference/introduction.mdx index e69de29..7616c45 100644 --- a/apps/docs/api-reference/introduction.mdx +++ b/apps/docs/api-reference/introduction.mdx @@ -0,0 +1,24 @@ +--- +title: Introduction +description: "Fundamental concepts of Usend's API." +--- + +## Base URL + +Unsend's API is built on REST principles and is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported. + +The Base URL for all API endpoints is: + +```sh Terminal +https://app.unsend.dev/api/ +``` + +## Authentication + +Authentication to Usend's API is performed via the Authorization header with a Bearer token. To authenticate, you need to include the Authorization header with the word Bearer followed by your token in your API requests like so: + +```sh Terminal +Authorization: Bearer us_12345 +``` + +You can create a new token/API key under your Unsend [Developer Settings](https://app.unsend.dev/api-keys). diff --git a/apps/docs/api-reference/openapi.json b/apps/docs/api-reference/openapi.json index b483905..8c16abe 100644 --- a/apps/docs/api-reference/openapi.json +++ b/apps/docs/api-reference/openapi.json @@ -106,6 +106,18 @@ }, "/v1/emails/{emailId}": { "get": { + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 3, + "example": "1212121" + }, + "required": true, + "name": "emailId", + "in": "path" + } + ], "responses": { "200": { "description": "Retrieve the user", diff --git a/apps/docs/get-started/nodejs.mdx b/apps/docs/get-started/nodejs.mdx new file mode 100644 index 0000000..329cd4b --- /dev/null +++ b/apps/docs/get-started/nodejs.mdx @@ -0,0 +1,35 @@ +--- +title: NodeJS +description: "Send your mail using unsend in NodeJS" +--- + +## Prerequisites + +- [Unsend API key](https://app.unsend.dev/api-keys) +- [Verified domain](https://app.unsend.dev/domains) + +## Code + +```js server.ts +const options = { + method: "POST", + headers: { + Authorization: "Bearer us_12345", + "Content-Type": "application/json", + }, + body: { + to: "jsmith@example.com", + from: "jsmith@example.com", + subject: "", + replyTo: "", + text: "", + html: "", + attachments: [{ filename: "", content: "" }], + }, +}; + +fetch("https://app.unsend.dev/api/v1/emails", options) + .then((response) => response.json()) + .then((response) => console.log(response)) + .catch((err) => console.error(err)); +``` diff --git a/apps/docs/introduction.mdx b/apps/docs/introduction.mdx index 49c8737..a71e725 100644 --- a/apps/docs/introduction.mdx +++ b/apps/docs/introduction.mdx @@ -30,4 +30,11 @@ Quicklinks to set up your account and get started > Learn how to use our API to send emails programmatically. + + Learn how to use our API to send emails programmatically. + diff --git a/apps/docs/mint.json b/apps/docs/mint.json index 5b055b0..b7e3852 100644 --- a/apps/docs/mint.json +++ b/apps/docs/mint.json @@ -47,11 +47,12 @@ { "group": "Get Started", "pages": [ - "introduction" + "introduction", + "get-started/nodejs" ] }, { - "group": "API Documentation", + "group": "API Reference", "pages": [ "api-reference/introduction" ] @@ -76,7 +77,7 @@ "method": "bearer" }, "playground": { - "mode": "simple" + "mode": "show" } }, "footerSocials": { diff --git a/apps/web/src/server/public-api/api-error.ts b/apps/web/src/server/public-api/api-error.ts index 08095ec..232a07c 100644 --- a/apps/web/src/server/public-api/api-error.ts +++ b/apps/web/src/server/public-api/api-error.ts @@ -7,14 +7,10 @@ const ErrorCode = z.enum([ "BAD_REQUEST", "FORBIDDEN", "INTERNAL_SERVER_ERROR", - "USAGE_EXCEEDED", - "DISABLED", "NOT_FOUND", "NOT_UNIQUE", "RATE_LIMITED", "UNAUTHORIZED", - "PRECONDITION_FAILED", - "INSUFFICIENT_PERMISSIONS", "METHOD_NOT_ALLOWED", ]); @@ -25,9 +21,6 @@ function codeToStatus(code: z.infer): StatusCode { case "UNAUTHORIZED": return 401; case "FORBIDDEN": - case "DISABLED": - case "INSUFFICIENT_PERMISSIONS": - case "USAGE_EXCEEDED": return 403; case "NOT_FOUND": return 404; @@ -35,8 +28,6 @@ function codeToStatus(code: z.infer): StatusCode { return 405; case "NOT_UNIQUE": return 409; - case "PRECONDITION_FAILED": - return 412; case "RATE_LIMITED": return 429; case "INTERNAL_SERVER_ERROR": @@ -52,12 +43,14 @@ function statusToCode(status: StatusCode): z.infer { return "UNAUTHORIZED"; case 403: return "FORBIDDEN"; - case 404: return "NOT_FOUND"; - case 405: return "METHOD_NOT_ALLOWED"; + case 409: + return "NOT_UNIQUE"; + case 429: + return "RATE_LIMITED"; case 500: return "INTERNAL_SERVER_ERROR"; default: diff --git a/apps/web/src/server/public-api/api/emails/get-email.ts b/apps/web/src/server/public-api/api/emails/get-email.ts index 55162df..dacff34 100644 --- a/apps/web/src/server/public-api/api/emails/get-email.ts +++ b/apps/web/src/server/public-api/api/emails/get-email.ts @@ -9,6 +9,20 @@ import { UnsendApiError } from "../../api-error"; const route = createRoute({ method: "get", path: "/v1/emails/{emailId}", + request: { + params: z.object({ + emailId: z + .string() + .min(3) + .openapi({ + param: { + name: "emailId", + in: "path", + }, + example: "cuiwqdj74rygf74", + }), + }), + }, responses: { 200: { content: {