@ambita/poc-api-design-system

✅ Status: Klar til bruk for eksterne brukere

Organizational API design system library for TypeSpec. Ensures all APIs across the organization follow the same design standards and patterns.

Biblioteket tilbyr:

- Norske domene-typer: Fødselsnummer, Organisasjonsnummer, Registerenhet, etc.
- Standard HTTP-operasjoner: ResourceGetList, ResourceGet, ResourcePost, ResourcePut
- Konsistente feilmeldinger: Standardiserte error responses med tidspunkt og feilmelding
- Paginering: Innebygd støtte for paginering i list-operasjoner

Installation

``bash
npm install @ambita/poc-api-design-system @typespec/compiler @typespec/http @typespec/rest @typespec/openapi
`

$3

1. Create or update your tspconfig.yaml:

`yaml
linter:
extends:
- poc-api-design-system/recommended
`

2. Import the library in your TypeSpec files:

`typespec
import "@ambita/poc-api-design-system";
import "@typespec/http";

using TypeSpec.Http;
using Ambita;

model User {
id: string;
navn: string;
foedselsnummer: Foedselsnummer;
}

@service({ title: "User API" })
@useAuth(AmbitaOAuth2)
namespace UserService {
@route("/users")
interface Users {
list is ResourceGetList;
get is ResourceGet;
create is ResourcePost;
}
}
`

Features

- Delte domene-typer: Strengt definerte skalare og value-objekter for norske datafelter
- Operasjonstemplater: Ferdige Resource*-operasjoner med HTTP-dekoratorer, paging og feilhåndtering
- Linteregler: TypeSpec-linteren sikrer at API-ene følger Ambita-mønstrene
- OAuth2-profiler: AmbitaOAuth2 eksponerer client credentials, password og Trusted-flow (egen back-end-legitimasjon)

Development

See WARP.md for development instructions and API_GUIDELINES.md for API design principles.

$3

lib/http/authentication.tsp definerer AmbitaOAuth2, som inkluderer tre flows:

- ClientCredentials mot https://api.ambita.com/authentication/v2/token
- PasswordFlow mot samme endepunkt (for systemer som trenger ressurs-eiers credentials)
- TrustedFlow (egen client-credential mot .../trusted/token) for spesielt sikrede back-end-kall

Bruk @useAuth(AmbitaOAuth2) på tjenesten din, og dokumenter hvilket flow klienten forventes å benytte.

$3

`bash


Run all tests

npm test

Run only linter rule tests (recommended for CI)

npm run test:rules
`

$3

Ingen kjente blokkere. npm test kjører alle linterregler via Node sitt innebygde testrammeverk – se USAGE.md for fullstendige eksempler.

Available Rulesets

- recommended: Recommended rules for most projects
- all`: All available rules enabled

License

ISC