DEV Community: Pete McFarlane

Leveraging the TS type system with APIs: Validation, error handling and free OpenAPI specs

Pete McFarlane — Thu, 03 Apr 2025 16:08:01 +0000

How many times have you been frustrated by out of date or incomplete API documentation? How many times have you realised that you were responsible for the out of date information?!
Building and maintaining API documentation that is an up-to-date reflection of the API itself can be a chore. Input validation and error handling can be hard to maintain, tricky to test, prone to inconsistencies, and easy to overlook. I'm going to explore how we can leverage the TypeScript type system to make these problems less of an issue, whilst generating API specifications for free! 💸

Common API issues

Inaccurate documentation

One thing worse than missing API documentation is out-of-date API documentation. If the documentation is written in a separate location to the API code then it becomes very manual to keep both in sync with each other. Even if as a developer making a change you remember to update the documentation, you could still introduce a subtle mistake. A common user mistake I've experienced for example is forgetting to nest a response value with a { data: {} } wrapper or similar.

Overlooking input validation

Then there's maintaining input validation - what if your API is expecting a UUID as an input but you're accidentally sending an auto-incrementing number, or post slug? What if your application just expects the input payload to be correct and complete, but it's missing required fields? You usually have to build a validation layer, so the API will respond to any incoming user request, then the validation layer will check if all the data is present and correct before continuing to handle the request.

In some codebases I've seen these validation checks repeated in multiple, subtly different ways - because it's more boiler plate for devs to manage and maintain, and it's often easy to introduce individual validation rules for each specific endpoint. This increases cognitive load for devs too as they have to handle the cases where the input is invalid, on-top of all other edge cases.

Inconsistent error handling

Then there's error handling - is there an issue with an invalid input? Or maybe the input is fine, but we've forgotten to authenticate the request? Perhaps the entity that was requested doesn't exist, or there's a foreign key constraint in the database, or an incorrect value selected for an enum, an input string that's too long - or another internal API call that isn't responding as we expect - there's a myriad of runtime errors that we need to think about handling and testing. If we want to test at the controller level, that typically means mocking or stubbing the request and response objects so we can monitor the behaviour.

Our Solution: TSOA

(Pronounced so·uh) is a Typescript library that generates OpenAPI compliant APIs and specs (OpenAPI specification is a language-agnostic definition format used to describe RESTful APIs), that can be added to your Express, Hapi, Koa or other NodeJS frameworks. It leverages the type system, meaning requests and responses are just represented as types. Extra details are added with annotations, e.g. @Route('/api/entities') or @Get('{entityId}). It removes the boiler plate for input validation and response or error handling, which also makes testing simpler. It can also generate API specs for us, meaning the docs are an up-to-date and accurately represent our API.

Example API definition

Lets say I have an API route that expects an entity id in the path. The entity should be in the format of a UUID. I can define this like so:

import { Controller, Get, Path, Route } from 'tsoa';

/**
 * Stringified UUIDv4.
 * See [RFC 4112](https://tools.ietf.org/html/rfc4122)
 * @pattern [0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}
 * @example "52907745-7672-470e-a803-a2f8feb52944"
 */
export type UUID = string;

export class EntityController extends Controller {
  /**
   * Retrieves an entity by its ID.
   */
  @Route('/entities/{entityId}')
  @Get()
  public async getEntity(
    @Path() entityId: UUID
  ): Promise<Entity> {
    // ... your logic to fetch the entity
    return this.entityService.getEntity(entityId);
  }
}

Notice how our function getEntity doesn't take a Request/Response/Next parameter like a typical Express callback? We're just using plain old fashioned Typescript Types, e.g return Promise<Entity> - this not only cleans up our code and is less to think about, it's also simpler to test.

Testing

Speaking of testing, let's look at a simple example of how we can test the getEntity method and its error handling using a testing framework like Jest:

describe('EntityController', () => {
  let mockEntityService: any;
  let controller: EntityController;
  const entityId = '52907745-7672-470e-a803-a2f8feb52944';

  beforeEach(() => {
    mockEntityService = {
      getEntity: jest.fn(),
    };
    controller = new EntityController(mockEntityService);
  });

  it('should return an entity if found', async () => {
    const mockEntity = { id: entityId, name: 'Test Entity', createdAt: new Date() };
    mockEntityService.getEntity.mockResolvedValue(mockEntity);

    const result = await controller.getEntity(entityId);
    expect(result).toEqual(mockEntity);
    expect(mockEntityService.getEntity).toHaveBeenCalledWith(entityId);
  });

  it('should throw HTTPError with 404 status if entity is not found', async () => {
    mockEntityService.getEntity.mockResolvedValue(null);

    await expect(controller.getEntity(entityId)).rejects.toBeInstanceOf(HTTPError);
    await expect(controller.getEntity(entityId)).rejects.toHaveProperty('status', 404);
    await expect(controller.getEntity(entityId)).rejects.toHaveProperty('message', 'Entity not found');
    expect(mockEntityService.getEntity).toHaveBeenCalledWith(entityId);
  });
});

In this test suite, notice how we are interacting directly with the controller's method and its TypeScript type signature. We are not setting up or manipulating mock req or res objects, making our tests more focused and easier to understand.

Error handling

The TSOA library is now going to make sure that any input (in the path, params, body or headers) matches what we've defined under our @Route annotation. But other errors can occur - for example, we might ask the entity service for an entity that doesn't exist! It'd be nice if, instead of exploding with a 500 unknown error, we could return a 404 not found with a helpful error message. I created a HttpError class to make managing these errors easier

export class HTTPError extends Error {
  constructor(message: string, public readonly status: number) {
    super(message);
  }
}

And here's a slightly simplified version of my error handler

export const errorHandler = (err: any, req: Request, res: Response, next: NextFunction) => {
  if (err instanceof ValidateError) {
    const body: ErrorResponse = {
      errors: {
        detail: {
          message: err.message,
          fields: err.fields,
        },
      },
    };
    res.status(422).json(body);
    next();
    return;
  }
  if (err instanceof HTTPError) {
    const body: ErrorResponse = {
      errors: {
        detail: err.message,
      },
    };
    res.status(err.status).json(body);
    next();
    return;
  }

  const status = err.status || 500;
  const body: ErrorResponse = {
    errors: {
      detail: err.message || 'Internal Server Error',
    },
  };

  res.status(status).json(body);
  next();
};

Authentication & Middleware

You can require authentication for certain routes by using the @Security('name', ['scopes']) decorator, where the name is preconfigured in a typescript module - much like any Express middleware. And you can add custom middleware to controllers or routes in much the same way, by using the @Middlewares decorator. One drawback here is the engineer has to remember to add those decorators!

Up-to-date generated API specs

And finally, because TSOA leverages your TypeScript types and decorators, it can automatically generate an OpenAPI-compliant specification (usually in JSON or YAML format) of your API. This generated specification can then be used by various tools and platforms, such as Swagger UI, code generation tools, and API gateways, ensuring your documentation is always up-to-date and accurate.

Drawbacks

It does introduce another dependency and another layer of abstraction in your application, and there may inevitably be a small performance overhead, but it may be less than you manually handling input validation and error handling anyway. I think it outweighs the drawbacks, but if performance is the most critical choice, you probably aren't using a NodeJS/Express service anyway!

If you are looking to do more advanced input validation, beyond pattern matching on strings, or some validation that can't be defined statically, e.g. authorisation - if a user can access an entity by ID - then you will still have to perform these checks in your code.

Alternatives

Zod seems to be the go-to validation library, and is very useful in some contexts, for example if you need to do more complex or nested runtime validation. But this won't generate API docs or give you error handlers or API controllers.

I noticed the NestJS framework has a module for generating docs from types and annotations, see their docs for a worked example.

OpenApi3-ts is a TS library that helps you build OpenAPI specs, but it doesn't do error handling, validation or replace your controllers!

tRPC can be a good option for creating type-safe APIs, which borrows concepts from REST and GraphQL. But this adds different tRPC boiler plate and ways-of-doing-things, which might be great for a backend/frontend monorepo situation for example, but might be harder to create a public facing API.

Conclusion

TSOA is pretty simple to introduce to an existing NodeJS/Express app, and will give you input validation generated API documentation out-the-box. Give it a try and share your feedback, on this or other approaches that have worked (or not!) for you.

Exploring PHP8 new goodies - match expression

Pete McFarlane — Thu, 10 Dec 2020 14:36:10 +0000

It's here, just in time for Christmas! I'm not sure how many will be using PHP8 in production this year, but that's not to say many of us aren't already trying it on smaller side projects to get a taste of some of the new features.

My favourite so far, the new match() expression.

Many other programming languages including Haskell, Erlang, and Elm, have a similar feature, but previously PHP only had the switch statement.

The switch statement is fine, but you have a few things to be mindful of.

Firstly a switch doesn't return a value, it's not an expression, although you can return early from a switch statement

switch ($operation) {
    case 'nop':
        return $this->nop();
    case 'acc':
       $this->acc($argument);
    case 'jmp':
       return $this->jmp($argument);
}

https://github.com/petemcfarlane/advent-of-code-2020/blob/8f5cc97377e2313e7fcbf60fb739e8084b01025e/day8/index.php

With a match this becomes much terser

return match ($operation) {
    'nop' => $this->nop(),
    'acc' => $this->acc($argument),
    'jmp' => $this->jmp($argument),
};

It's also easier to prevent mistakes, like forgetting to return on the "acc" branch in the previous switch example.

A match can match multiple values, if they are comma separated, so I could write the above as

return match ($operation) {
    'nop' => $this->nop(),
    'acc', 'jmp' => $this->{$operation}($argument),
};

Although in this case I'm not sure it's particularly easier to read.

There is a default branch you can use if you want to specify what should be returned if there is no match. You can also use arbitrary functions for comparisons in the match conditions.

function validateEmail(string $email): string
{
    return match (true) {
        str_contains($email, '@example.com') => 'an example email',
        $email === filter_var($email, FILTER_VALIDATE_EMAIL) => 'a valid email',
        default => throw new InvalidArgumentException('Invalid email address')
    };
}

var_dump(validateEmail('hello@example.com')); // returns 'an example email'
var_dump(validateEmail('foo@bar.com')); // returns 'a valid email'
var_dump(validateEmail('invalid email')); // throws InvalidArgumentException

In this example I'm also taking advantage of being able to throw exceptions in

We also get a new UnhandledMatchError if we forget to declare a path. This can be somewhat useful, like the PHP7 TypeError, as the exception includes the type of value we tried to match, but not the value itself.

It would be really cool to be able to do partial matches or some kind of destructuring in the future, not sure if this going to be at all possible, something like

class A {
    public function __construct(public int $n) {}
}

class B {
    public function __construct(public int $n) {}
}

$x = new A(1); // or new B(2);

match ($x) {
    new A($n) => $n,
    new B($n) => $n,
};

Chaos branching in Git

Pete McFarlane — Thu, 07 May 2020 08:20:40 +0000

When you're working on a feature branch, but that feature branch has had a lot of merges with other branches and sub-feature branches, you just want to unset the diff between all the files in one, chaos branch, and master you can run

> git checkout yourBranch
> git reset $(git merge-base master yourBranch)

(source from StackOverflow answer)

Now you have one big change list, it's time to use git commit -p or your favourite git GUI to make selective commits into something more logical, ready to submit as a pull request.

PHP 7.4 in prod at last

Pete McFarlane — Thu, 30 Jan 2020 20:26:29 +0000

This week we finally moved to PHP 7.4 in production at work. The upgrade has been the most anticipated (by me) since PHP 7.

The new hotness of short functions, typed properties, not to mention improved performance by file preloading, array spread syntax, null coalesce and a host of other improvements!

The only caveats we had upgrading were a few packages were fixed to PHP 7.3 (these have since been upgraded) and we require php-redis extension which is now installed with PECL.

Moving to production went fairly smoothly, to say we're still reliant on Chef and AWS Opsworks which both seem pretty outdated stacks for 2020 (hoping to move to containers soon!)

I really like the language improvements, feels like we're coming more mature as a language and taking inspiration from JavaScript, Java and others. It will be interesting to see the future development and what the future holds for PHP!

Have you upgraded yet? If so, what's your favourite new feature/improvement? If not, what's stopping you?!