EIN-4783: TypeSpec

.github/workflows/build-openapi.yml

@@ -0,0 +1,34 @@
+name: Build OpenAPI and commit changes
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build-and-commit:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bun run build
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "Codegen"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global commit.gpgSign true
+
+      - name: Commit and push changes
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git add .
+          if git diff --cached --quiet; then
+            echo "No changes to commit."
+          else
+            git commit -S -m "Build OpenAPI from TypeSpec"
+            git push origin HEAD:${{ github.head_ref }}
+          fi

.gitignore

@@ -0,0 +1,2 @@
+**/node_modules
+**/tsp-output

README.md

@@ -1,2 +1,110 @@
-# ein-openapi
-OpenAPI specification for eInnsyn
+# <img src="https://einnsyn.no/8ebf89f8e40d3eb75183.svg" width="180px" alt="eInnsyn"/>
+
+This repository contains the API specification for [eInnsyn](https://einnsyn.no)'s API. The API is written in [TypeSpec](https://typespec.io), with an auto-generated OpenAPI version in the [openapi](openapi)-folder.
+
+The [typespec](typespec)-folder contains the following files:
+- `einnsyn.arkiv.models.tsp`: Model definition for archive data, mostly  Noark 5 with some extensions for meetings.
+- `einnsyn.arkiv.operations.tsp`: Endpoints for archive models.
+- `einnsyn.queryparameters.tsp`: Base models for query parameters.
+- `einnsyn.responses.tsp`: Models for API responses.
+- `einnsyn.web.models.tsp`: Models for entities that are mainly used for the eInnsyn website, not related to archive data.
+- `einnsyn.web.operations.tsp`: Endpoints for web models.
+
+
+## Authentication
+
+The eInnsyn API uses API keys to authenticate requests. The keys are long-lived, and should be handled carefully. All API keys are prefixed with `secret_`.
+
+To send an authenticated request, the API key should be sent in the `X-EIN-API-KEY` header:
+
+```
+curl -H "X-EIN-API-KEY: secret_..." https://api.einnsyn.no
+```
+
+## General endpoint structure
+
+All entities has standard CRUD-endpoints:
+- `POST /{entityName}`: Create object
+- `GET /{entityName}`: Get a paginated list of objects
+- `GET /{entityName}/{id}`: Get an object
+- `PATCH /{entityName}/{id}`: Update an object
+- `DELETE /{entityName}/{id}`: Delete an object
+
+## IDs
+
+All objects in eInnsyn will get an auto-generated `eInnsynId`. An eInnsynId is a Base32 encoded UUID, with a prefix to indicate the type of resource. In the API specification, all entities has an extension annotation describing it's ID prefix.
+
+Example annotation for the Journalpost entity: `@extension("x-idPrefix", "jp")`.
+
+Example journalpost ID: `jp_01jh532p3ve6haq7n53xgpqayh`
+
+In addition, all Noark5 objects must have a globally unique systemId assigned by the publisher. This identifier can be used interchangeably with the eInnsynId in the API.
+
+## Expanding responses
+
+We use a concept called "expandable fields", inspired by Stripe's API ([Expanding Responses](https://docs.stripe.com/api/expanding_objects)). Throughout the API, all references to entity objects are either an ID, or the actual object. By default, all nested objects in a `GET` response are sent as an ID. For `POST` and `PATCH` requests, all new objects are returned. If you need to access to nested objects, you can use the `expand` query parameter:
+
+### Default expansion:
+
+```
+curl -H "X-EIN-API-KEY: secret\_..." https://api.einnsyn.no/saksmappe/sm_01jh50h5brf7wrbwga8xd0rwdy
+{
+  "entity": "Saksmappe", 
+  "id": "sm_01jh532p0jfdh8j3evmpgk4atx",
+  ...
+  "journalpost": [
+    "jp_01jh532p3ve6haq7n53xgpqayh"
+  ]
+}
+```
+
+### Expand `journalpost`:
+
+```
+curl ... https://api.einnsyn.no/saksmappe/sm_01jh50h5brf7wrbwga8xd0rwdy?expand=journalpost
+{
+  "entity": "Saksmappe",
+  "id": "sm_01jh532p0jfdh8j3evmpgk4atx",
+  ...
+  "journalpost": [{
+    "entity": "Journalpost",
+    "id": "jp_01jh532p3ve6haq7n53xgpqayh",
+    ...
+    "korrespondansepart": [
+      "kp_01jh532p50epvvcjfv8xrzzwp5",
+      "kp_01jh532p6qfhxrz1w9fdw4jjrh"
+    ]
+  }]
+}
+```
+
+### Expand `journalpost.korrespondansepart`:
+
+```
+curl ... https://api.einnsyn.no/saksmappe/sm_01jh50h5brf7wrbwga8xd0rwdy?expand=journalpost.korrespondansepart
+{
+  "entity": "Saksmappe",
+  "id": "sm_01jh532p0jfdh8j3evmpgk4atx",
+  ...
+  "journalpost": [{
+    "entity": "Journalpost",
+    "id": "jp_01jh532p3ve6haq7n53xgpqayh",
+    ...
+    "korrespondansepart": [{
+      "entity": "Korrespondansepart",
+      "id": "kp_01jh532p50epvvcjfv8xrzzwp5",
+      ...
+    },
+    {
+      "entity": "Korrespondansepart",
+      "id": "kp_01jh532p6qfhxrz1w9fdw4jjrh",
+      ...
+    }]
+  }]
+}
+```
+
+## Client libraries
+
+Client libraries for Java and TypeScript are in the works. We're also considering a .NET client library.
+