@apolitical/contracts NPM

Apolitical / Contracts

An Nx library and NPM package for defining and interacting with Apolitical API endpoints, designed to streamline development with consistent contracts and robust type safety.

Note that @apolitical/contracts has been recently refactored to follow the RFC for consolidating contracts. Please refer to the RFC for more info on the new structure.

Overview

@apolitical/contracts provides:

Unified API contracts: Standardized TypeScript definitions for API endpoints
Developer-friendly structure: A simplified and intuitive folder layout
Type safety: Ensures reliable and predictable API interactions

For more on the underlying technology, check out ts-rest.

Structure

The new structure would look like this:

/src
  /apis
    /mgmt-api
      /accounts
        accounts.contract.ts
        connections.contract.ts
        index.ts
      mgmt-api.contract.ts
      mgmt-api.types.ts
      index.ts
    // more APIs here
  /ts
    /i18n
      i18n.constants.ts
      i18n.enums.ts
      i18n.types.ts
    // more files here
  /zod
    /extensions
    index.ts
  index.ts

Briefly:

/src/apis contains the contracts for each API
/src/ts contains the shared types, enums and constants
/src/zod contains the shared zod extensions

Usage

Creating a new resource

Let’s imagine you have to create a new endpoint POST /images within the assets-api, so then the steps to create the contract for that new endpoint are as follows:

Locate the assets-api at /backend/v2/libs/contracts/src/apis/assets-api
Given that the Image is a new resource within assets-api, we create a images.contract.ts file (as described here)
Implement images subcontract with it’s new create method (as described here)
Add the images subcontract to the assets top-contract at assets-api.contract.ts file
Expose any shared types at assets-api.types.ts
1. If there is a shared enum, define it at assets-api.enums.ts
2. If there is a shared constant, define it at assets-api.constants.ts

Creating a nested resource

Let’s imagine you have to create a new endpoint POST /learners/:id/images within the assets-api, so then the steps to create the contract for that new endpoint are as follows:

Locate the assets-api at /backend/v2/libs/contracts/src/apis/assets-api
If the learners folder doesn’t exist create one (note that the learners folder is created to encapsulate the learners.contract.ts and the images.contract.ts as the images contract is a subcontract of learners).
Follow the steps describe above, but exposing the subcontracts in right order of hierarchy, in this case assets → learners → images

Integrating with Nest.js endpoints

We follow the Nest.js integration guide to integrate with Nest.js endpoints. In particular, we use the @TsRestHandler decorator to define the handler for the endpoint as we are progressing towards a fully ts-rest-fied Nest.js setup.

Consuming the client on the frontend

We follow the ts-rest client guide to consume the client on the frontend. In particular, we use the Fetch Client to interact with the APIs from the frontend. This means that 4/5xx status codes will not throw an error, so you must check for these codes explicitly.

Building

Run nx build contracts to build the library.

Running unit tests

Run nx test contracts to execute the unit tests via Jest.

Adding a locale

From the root of contracts run

node add-locale.js --locale <localeCode> --englishName <EnglishName> --nativeName <nativeName> --flag <flag>

for example

node add-locale.js --locale sv --englishName "Swedish" --nativeName "Svenska" --flag "🇸🇪"

zod @ts-rest/core tslib insane slugify xss @anatine/zod-openapi graphql getstream

@apolitical/component-library

10 months ago

10 months ago

8 months ago

10 months ago

10 months ago

12 months ago

11 months ago

11 months ago

11 months ago

11 months ago

7 months ago

11 months ago

11 months ago

10 months ago

11 months ago

6 months ago

6 months ago

7 months ago

11 months ago

12 months ago

12 months ago

12 months ago

9 months ago

12 months ago

12 months ago

12 months ago

8 months ago

12 months ago

12 months ago

8 months ago

10 months ago

8 months ago

8 months ago

8 months ago

6 months ago

9 months ago

11 months ago

9 months ago

9 months ago

9 months ago

6 months ago

9 months ago

8 months ago

8 months ago

9 months ago

9 months ago

9 months ago

7 months ago

7 months ago

9 months ago

7 months ago

8 months ago

7 months ago

7 months ago

9 months ago

10 months ago

10 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

10 months ago

10 months ago

10 months ago

10 months ago

7 months ago

10 months ago

7 months ago

7 months ago

7 months ago

10 months ago

11 months ago

6 months ago

7 months ago

10 months ago

8 months ago

8 months ago

8 months ago

8 months ago

7 months ago

8 months ago

8 months ago

7 months ago

7 months ago

8 months ago

8 months ago

9 months ago

6 months ago

6 months ago

6 months ago

6 months ago

8 months ago

7 months ago

12 months ago

12 months ago

12 months ago

7 months ago

8 months ago

10 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

10 months ago

12 months ago

9 months ago

10 months ago

10 months ago

10 months ago

8 months ago

8 months ago

8 months ago

10 months ago

10 months ago

7 months ago

8 months ago

10 months ago

9 months ago

8 months ago

11 months ago

11 months ago

11 months ago

8 months ago

7 months ago

8 months ago

8 months ago

8 months ago

11 months ago

8 months ago

11 months ago

8 months ago

8 months ago

8 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

6 months ago

9 months ago

9 months ago

9 months ago

8 months ago

8 months ago

8 months ago

8 months ago

11 months ago

7 months ago

7 months ago

11 months ago

7 months ago

11 months ago

11 months ago

11 months ago

10 months ago

10 months ago

10 months ago

8 months ago

9 months ago

9 months ago

10 months ago

11 months ago

7 months ago

7 months ago

9 months ago

8 months ago

9 months ago

9 months ago

10 months ago

8 months ago

12 months ago

7 months ago

11 months ago

8 months ago

8 months ago

8 months ago

9 months ago

9 months ago

8 months ago

11 months ago

10 months ago

11 months ago

9 months ago

11 months ago

11 months ago

10 months ago

11 months ago

9 months ago

11 months ago

6 months ago

10 months ago

6 months ago

10 months ago

6 months ago

6 months ago

8 months ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago