Benjamin Sitruk bsitruk

REST API - OpenAPI Error Response

#api#best-practice

When writing the OpenAPI specs of an API, which error case should I document in the "response" section ?

In OpenAPI you only need to describe the responses that the client can realistically expect and act on for a given operation. The spec itself clarifies that the document

“is not necessarily expected to cover all HTTP response codes … however, it is expected to cover a successful operation response and any known errors.” (swagger.io)

Serialization and Parsing Dates in JS

1. Agree on the “over-the-wire” shape first

Concern	Recommended format	Why
Dates	ISO-8601 UTC string (`2025-06-18T12:34:56.789Z`)	Human-readable, sortable, handled natively by every major client.
BigInt	String	Avoids loss of precision in JS JSON.
Binary	Base-64 string (or separate download URL)	Plays nicely with text-only transports.

	import * as cluster from 'cluster';
	import * as os from 'os';
	import { Logger } from '@nestjs/common';

	export class Cluster {
	static register(workers: number, logger: Logger, callback: CallableFunction): void {
	const cpuCount = os.cpus().length;

	if (cluster.isMaster) {
	logger.log(`master process started on ${process.pid}`);

	const keys = ['k1', 'k2', 'k3']
	const Keys = typeof keys[number]

	type Object = {
	k1: number,
	k2: boolean
	}

	type KeyValue = {
	[k in Keys]: k extends keyof Object ? Object[k] : unknown

	// Sort List of Objects By Two Keys
	type SortKey<T> = {
	key: keyof T;
	order: 1 \| -1;
	};
	export function sortByKeys<T>(list: T[], keys: SortKey<T> \| [SortKey<T>, SortKey<T>]) {
	if (!Array.isArray(keys)) {
	const { key: sortKey, order } = keys;
	return list.sort((v1, v2) => (v1[sortKey] < v2[sortKey] ? order * 1 : -1 * order));
	}

	Constrained Identity Function


	- Use Case: We want to create a Record with a limited set of Keys, and a defined type of Values.
	- We also don't want to Type the Set of Keys, but leverage TypeScript inference instead (DRY)
	- If we create a new inline object literal, TypeScript will prevent any new key from being added, by won't enforce the type of the Values.
	- So Narrow Keys, Wide Value Type
	- If we specify the type Record<string, number>, we'll be able to add any new Key after the object creation
	- So Wide Keys, Narrow Value Type
	- By using a Types Identity Function, we can build an object with enforced Value Type, and Narrow set of Keys.

	#!/usr/bin/env zx

	# usage
	#./keys-to-enum.mjs "{ 220ms  Thu Aug 25 11:04:52 2022
	# attributeName,
	# fieldName,
	# fullyQualifiedName,
	# attributeType,
	# scannerTypeGroup,
	# }: GetRecordFindingsDto"

	https://stackoverflow.com/questions/22944631/how-to-get-the-ip-address-of-the-docker-host-from-inside-a-docker-container

	docker run -it --rm alpine nslookup host.docker.internal

	#!/bin/bash

	# Function to purge a queue
	purge_queue() {
	queue_name="$1"
	echo "Purging queue: $queue_name"
	docker exec CONTAINER_NAME rabbitmqadmin -u USER -p PWD -H 0.0.0.0 -P MANAGEMENT_PORT purge queue name="$queue_name" > /dev/null
	}

	# Fetch all queues

	#!/bin/bash

	# Check for correct number of arguments
	if [ "$#" -ne 2 ]; then
	echo "Usage: $0 <PID> <Label>"
	exit 1
	fi

	PID=$1
	LABEL=$2