diff --git a/npm-shrinkwrap.json b/npm-shrinkwrap.json index 2c5c0f19..b674b813 100644 --- a/npm-shrinkwrap.json +++ b/npm-shrinkwrap.json @@ -1,11 +1,11 @@ { - "name": "api.opensauced.pizza", + "name": "@open-sauced/api.opensauced.pizza", "version": "1.12.0-beta.1", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "api.opensauced.pizza", + "name": "@open-sauced/api.opensauced.pizza", "version": "1.12.0-beta.1", "license": "MIT", "dependencies": { diff --git a/package.json b/package.json index 37197cfd..4ed1bf6f 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "api.opensauced.pizza", + "name": "@open-sauced/api.opensauced.pizza", "version": "1.12.0-beta.1", "keywords": [], "description": "API dot Open Sauced is NestJS and SupaBase powered OAS3 backend designed to remove client complexity and provide a structured graph of all @open-sauced integrations", diff --git a/src/config/api.config.ts b/src/config/api.config.ts index 491d61dd..0f284ac2 100644 --- a/src/config/api.config.ts +++ b/src/config/api.config.ts @@ -4,7 +4,7 @@ export default registerAs("api", () => ({ host: String(process.env.API_HOST ?? "0.0.0.0"), port: String(process.env.API_PORT ?? "3001"), domain: String(process.env.API_DOMAIN ?? "api.opensauced.pizza"), - development: (/watch/).test(String(process.env.npm_lifecycle_script ?? "node")), + development: String(process.env.npm_lifecycle_script ?? "node").includes("watch"), memory_heap: Number(parseInt(process.env.MEMORY_HEAP ?? "200", 10) * 1024 * 1024), memory_rss: Number(parseInt(process.env.MEMORY_RSS ?? "3000", 10) * 1024 * 1024), disk_percentage: Number(parseFloat(process.env.DISK_PERCENGATE ?? "0.7")), diff --git a/src/main.ts b/src/main.ts index c49e6e40..9fa8c878 100644 --- a/src/main.ts +++ b/src/main.ts @@ -13,7 +13,7 @@ import { writeFile } from "node:fs/promises"; import { major } from "semver"; import { AppModule } from "./app.module"; -import { name, description, version, license } from "../package.json"; +import { name, version, license } from "../package.json"; async function bootstrap () { const app = await NestFactory.create( @@ -21,6 +21,50 @@ async function bootstrap () { new FastifyAdapter({ logger: false }), ); const configService = app.get(ConfigService); + const apiDomain = String(configService.get("api.domain")); + + const markdownDescription = ` +## Swagger-UI API Documentation + +This REST API can be used to create, read, update or delete data from the Open Sauced community platform. +The Swagger-UI provides useful information to get started and an overview of all available resources. +Each API route is clickable and has their own detailed description on how to use it. +The base URL for the API is [${apiDomain}](https://${apiDomain}). + +[comment]: # (TODO: add bearer auth information) + +## Rate limiting + +Every IP address is allowed to perform 5000 requests per hour. +This is measured by saving the date of the initial request and counting all requests in the next hour. +When an IP address goes over the limit, HTTP status code 429 is returned. +The returned HTTP headers of any API request show the current rate limit status: + +header | description +--- | --- +\`X-RateLimit-Limit\` | The maximum number of requests allowed per hour +\`X-RateLimit-Remaining\` | The number of requests remaining in the current rate limit window +\`X-RateLimit-Reset\` | The date and time at which the current rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) + +[comment]: # (TODO: add pagination information) + +## Common response codes + +Each route shows for each method which data they expect and which they will respond when the call succeeds. +The table below shows most common response codes you can receive from our endpoints. + +code | condition +--- | --- +[\`200\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) | The [\`GET\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) request was handled successfully. The response provides the requested data. +[\`201\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201) | The [\`POST\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) request was handled successfully. The response provides the created data. +[\`204\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204) | The [\`PATCH\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) or [\`DELETE\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) request was handled successfully. The response provides no data, generally. +[\`400\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400) | The server will not process the request due to something that is perceived to be a client error. Check the provided error for mote information. +[\`401\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401) | The request requires user authentication. Check the provided error for more information. +[\`403\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403) | The request was valid, but the server is refusing user access. Check the provided error for more information. +[\`404\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404) | The requested resource could not be found. Check the provided error for more information. +[\`429\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) | The current API Key made too many requests in the last hour. Check [Rate limiting](#ratelimiting) for more information. + +## Additional links`; app.enableCors(); app.enableVersioning({ @@ -35,14 +79,14 @@ async function bootstrap () { } options - .addServer(`https://${configService.get("api.domain")}`, "Production") - .addServer(`https://beta.${configService.get("api.domain")}`, "Beta") + .addServer(`https://${apiDomain}`, "Production") + .addServer(`https://beta.${apiDomain}`, "Beta") .setTitle(name) - .setDescription(description) + .setDescription(markdownDescription) .setVersion(version) - .setContact("Open Sauced Triage Team", "https://opensauced.pizza", "hello@opensauced.pizza") + .setContact("Open Sauced", "https://opensauced.pizza", "hello@opensauced.pizza") .setTermsOfService("https://github.com/open-sauced/code-of-conduct") - .setLicense(license, `https://opensource.org/licenses/${license}`) + .setLicense(`The ${license} License`, `https://opensource.org/licenses/${license}`) .addBearerAuth(); const document = SwaggerModule.createDocument(app, options.build(), {