@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

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

Configuration

1. Create or update your tspconfig.yaml:

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

2. Import the library in your TypeSpec files:

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<User>;
    get is ResourceGet<User,string>;
    create is ResourcePost<User, User>;
  }
}

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.

Authentication

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.

Running Tests

# Run all tests
npm test

# Run only linter rule tests (recommended for CI)
npm run test:rules

Known Issues

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