@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, RegisterenhetKey, etc.
• Standard HTTP-operasjoner: ResourceGetList, ResourceGet, ResourcePost, ResourcePut, ResourceDelete
• Hurtigstart-CRUD: CrudResource<T, TId> gir alle fem endepunktene i én linje
• Konsistente feilmeldinger: RFC 9457 Problem Details på alle feilresponser
• Paginering: Innebygd støtte for paginering i list-operasjoner
• Versjonering: Kanoniske API-versjoner via Ambita.Versions

Installation

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

@typespec/openapi3 er OpenAPI-emitteren som genererer selve spesifikasjonen. Den er ikke en peer dependency, så konsumenter må installere den selv.

Configuration

1. Create or update your tspconfig.yaml:

emit:
  - "@typespec/openapi3"

options:
  "@typespec/openapi3":
    emitter-output-dir: "{project-root}/tsp-output/schema"
    output-file: "openapi.{version}.yaml"
    openapi-versions:
      - 3.1.0

linter:
  extends:
    - "@ambita/poc-api-design-system/recommended"

Bruk {version}-plassholderen i output-file. Emitteren skriver én fil per API-versjon, så et hardkodet filnavn ville føre til at v2 overskriver v1 når du legger til en ny versjon. openapi-versions styrer OpenAPI-formatet (3.1.0), og er noe annet enn API-versjonen din.

2. Import the library in your TypeSpec files:

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

using TypeSpec.Http;
using TypeSpec.Versioning;
using Ambita;

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

@service(#{ title: "User API" })
@versioned(Ambita.Versions)
@useAuth(AmbitaOAuth2)
namespace UserService {
  // Hele CRUD-flaten: GET/POST /users og GET/PUT/DELETE /users/{id}
  @route("/users")
  interface Users extends CrudResource<User> {}
}

Trenger du bare deler av flaten, eller egne request-modeller, bruk operasjonstemplatene direkte på rot-nivå (op listUsers is ResourceGetList<User>;) – se USAGE.md.

3. Kompiler:

npx tsp compile .

Resultatet havner i tsp-output/schema/openapi.v1.yaml.

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)
• Versjonering: Ambita.Versions gir felles versjonsnavn på tvers av tjenester, og fyller info.version i OpenAPI-outputen

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.

Versioning

lib/http/versioning.tsp definerer Ambita.Versions – de kanoniske API-versjonene for Ambita-tjenester. Enumet inneholder i dag kun v1.

Annotér tjenesten din med @versioned(Ambita.Versions) og legg til using TypeSpec.Versioning; i fila (using er fil-scopet, så bibliotekets egen import holder ikke). Uten denne annoteringen emitteres info.version som 0.0.0.

Ved breaking changes:

1. Legg til en ny verdi i enumet, f.eks. v2: "v2"
2. Annotér endringene med @added(Ambita.Versions.v2), @removed eller @renamedFrom
3. Emitteren produserer nå både openapi.v1.yaml og openapi.v2.yaml

Merk at enumet ligger i dette delte biblioteket, ikke i den enkelte tjenesten. Å legge til en versjon er derfor en endring som treffer alle konsumenter, og krever en ny release av biblioteket.

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