Skip to content

Commit 5430c22

Browse files
gnegne
authored
Merge pull request #25 from felleslosninger/gne-readme
Update README.md
2 parents 0a2dbdb + 51e23c6 commit 5430c22

File tree

2 files changed

+80
-51
lines changed

2 files changed

+80
-51
lines changed

‎README.md‎

Lines changed: 79 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
# <img src="https://einnsyn.no/8ebf89f8e40d3eb75183.svg" width="180px" alt="eInnsyn"/>
22

3-
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.
3+
This repository contains the API specification for [eInnsyn](https://einnsyn.no)'s API. The API is written in [TypeSpec](https://typespec.io), and the generated OpenAPI document is available at [openapi/einnsyn.openapi.yml](openapi/einnsyn.openapi.yml).
44

5-
The [typespec](typespec)-folder contains the following files:
5+
The main files in the [typespec](typespec)-folder are:
66

7+
- [einnsyn.tsp](typespec/einnsyn.tsp): Entry point for the API, including service metadata and authentication.
8+
- [einnsyn.exceptions.tsp](typespec/einnsyn.exceptions.tsp): Shared exception and error response definitions.
79
- [einnsyn.arkiv.models.tsp](typespec/einnsyn.arkiv.models.tsp): Model definition for archive data, mostly Noark 5 with some extensions for meetings.
810
- [einnsyn.arkiv.operations.tsp](typespec/einnsyn.arkiv.operations.tsp): Endpoints for archive models.
911
- [einnsyn.queryparameters.tsp](typespec/einnsyn.queryparameters.tsp): Base models for query parameters.
@@ -13,99 +15,126 @@ The [typespec](typespec)-folder contains the following files:
1315

1416
## Authentication
1517

16-
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_`.
18+
The eInnsyn API uses API keys to authenticate requests. To send an authenticated request, include the API key in the `API-KEY` header:
1719

18-
To send an authenticated request, the API key should be sent in the `X-EIN-API-KEY` header:
19-
20-
```
21-
curl -H "X-EIN-API-KEY: secret_..." https://api.einnsyn.no
20+
```sh
21+
curl -H "API-KEY: <api-key>" https://api.einnsyn.no
2222
```
2323

2424
## General endpoint structure
2525

26-
All entities has standard CRUD-endpoints:
26+
Most routable resources expose standard CRUD endpoints:
2727

2828
- `GET /{entityName}`: Get a paginated list of objects
2929
- `GET /{entityName}/{id}`: Get an object
3030
- `PATCH /{entityName}/{id}`: Update an object
3131
- `DELETE /{entityName}/{id}`: Delete an object
3232

33-
Objects that do not require a parent object (primarily arkiv) can be added directly at the root level using `POST /{entityName}`. However, objects that require a parent must be added through the parent object, for example: `POST /arkiv/ar_.../arkivdel`.
33+
Resources that do not require a parent object can usually be added directly at the root level using `POST /{entityName}`. Resources that require a parent are added through the parent resource, for example `POST /arkiv/{id}/arkivdel`.
34+
35+
The API also includes task-specific endpoints such as `/search`, `/statistics`, and `/me`.
36+
37+
## Pagination
38+
39+
List endpoints use cursor-based pagination. You can control page size with `limit` (between 1 and 100, default 25), use `startingAfter` to fetch the next page, and `endingBefore` to paginate backwards. List responses contain an `items` array and may include `next` and `previous` URLs:
40+
41+
```sh
42+
curl -H "API-KEY: <api-key>" "https://api.einnsyn.no/journalpost?limit=2"
43+
{
44+
"items": [
45+
{
46+
"entity": "Journalpost",
47+
"id": "jp_01jh532p3ve6haq7n53xgpqayh"
48+
},
49+
{
50+
"entity": "Journalpost",
51+
"id": "jp_01jh532p6qfhxrz1w9fdw4jjrh"
52+
}
53+
],
54+
"next": "https://api.einnsyn.no/journalpost?limit=2&startingAfter=jp_01jh532p6qfhxrz1w9fdw4jjrh",
55+
"previous": null
56+
}
57+
```
58+
59+
If you pass `ids` or `externalIds`, the other list parameters are ignored.
3460

3561
## IDs
3662

37-
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.
63+
All objects in eInnsyn get an auto-generated `eInnsynId`. An `eInnsynId` is a Base32-encoded UUID with a prefix that indicates the type of resource. In the API specification, each entity has an extension annotation describing its ID prefix.
3864

3965
Example annotation for the Journalpost entity: `@extension("x-idPrefix", "jp")`.
4066

4167
Example journalpost ID: `jp_01jh532p3ve6haq7n53xgpqayh`
4268

4369
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.
4470

71+
## Read-only and write-only fields
72+
73+
Some fields are only available during certain lifecycle stages. In the TypeSpec source, this is expressed with `@visibility(...)`.
74+
75+
- Read-only fields are returned by `GET` requests, but are not meant to be sent when creating or updating resources.
76+
- Write-only fields can be sent when creating or updating resources, but are omitted from `GET` responses.
77+
78+
For example, `Saksmappe.saksnummer` and `Saksmappe.administrativEnhetObjekt` are read-only, while `Saksmappe.journalpost` is write-only. Because of that, `journalpost` is not returned by `GET /saksmappe/{id}` and cannot be expanded there. To read the journalposts for a case, use `GET /saksmappe/{id}/journalpost` instead.
79+
4580
## Expanding responses
4681

47-
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 nested objects, you can use the `expand` query parameter:
82+
We use a concept called "expandable fields", inspired by Stripe's API ([Expanding Responses](https://docs.stripe.com/api/expanding_objects)). Throughout the API, references to entity objects are either an ID or the expanded object. On endpoints that support `expand`, nested objects in a `GET` response are sent as IDs by default. If you need nested objects, you can use the `expand` query parameter:
4883

4984
### Default expansion:
5085

51-
```
52-
curl -H "X-EIN-API-KEY: secret\_..." https://api.einnsyn.no/saksmappe/sm_01jh50h5brf7wrbwga8xd0rwdy
86+
```sh
87+
curl -H "API-KEY: <api-key>" https://api.einnsyn.no/journalpost/jp_01jh532p3ve6haq7n53xgpqayh
5388
{
54-
"entity": "Saksmappe",
55-
"id": "sm_01jh532p0jfdh8j3evmpgk4atx",
89+
"entity": "Journalpost",
90+
"id": "jp_01jh532p3ve6haq7n53xgpqayh",
5691
...
57-
"journalpost": [
58-
"jp_01jh532p3ve6haq7n53xgpqayh"
59-
]
92+
"saksmappe": "sm_01jh50h5brf7wrbwga8xd0rwdy"
6093
}
6194
```
6295

63-
### Expand `journalpost`:
96+
### Expand `saksmappe`:
6497

65-
```
66-
curl ... https://api.einnsyn.no/saksmappe/sm_01jh50h5brf7wrbwga8xd0rwdy?expand=journalpost
98+
```sh
99+
curl ... https://api.einnsyn.no/journalpost/jp_01jh532p3ve6haq7n53xgpqayh?expand=saksmappe
67100
{
68-
"entity": "Saksmappe",
69-
"id": "sm_01jh532p0jfdh8j3evmpgk4atx",
101+
"entity": "Journalpost",
102+
"id": "jp_01jh532p3ve6haq7n53xgpqayh",
70103
...
71-
"journalpost": [{
72-
"entity": "Journalpost",
73-
"id": "jp_01jh532p3ve6haq7n53xgpqayh",
104+
"saksmappe": {
105+
"entity": "Saksmappe",
106+
"id": "sm_01jh50h5brf7wrbwga8xd0rwdy",
107+
"saksnummer": "2025/1234",
74108
...
75-
"korrespondansepart": [
76-
"kp_01jh532p50epvvcjfv8xrzzwp5",
77-
"kp_01jh532p6qfhxrz1w9fdw4jjrh"
78-
]
79-
}]
109+
"administrativEnhetObjekt": "enh_01jh532p50epvvcjfv8xrzzwp5"
110+
}
80111
}
81112
```
82113

83-
### Expand `journalpost.korrespondansepart`:
114+
### Expand `saksmappe.administrativEnhetObjekt`:
84115

85-
```
86-
curl ... https://api.einnsyn.no/saksmappe/sm_01jh50h5brf7wrbwga8xd0rwdy?expand=journalpost.korrespondansepart
116+
```sh
117+
curl ... https://api.einnsyn.no/journalpost/jp_01jh532p3ve6haq7n53xgpqayh?expand=saksmappe.administrativEnhetObjekt
87118
{
88-
"entity": "Saksmappe",
89-
"id": "sm_01jh532p0jfdh8j3evmpgk4atx",
119+
"entity": "Journalpost",
120+
"id": "jp_01jh532p3ve6haq7n53xgpqayh",
90121
...
91-
"journalpost": [{
92-
"entity": "Journalpost",
93-
"id": "jp_01jh532p3ve6haq7n53xgpqayh",
122+
"saksmappe": {
123+
"entity": "Saksmappe",
124+
"id": "sm_01jh50h5brf7wrbwga8xd0rwdy",
125+
"saksnummer": "2025/1234",
94126
...
95-
"korrespondansepart": [{
96-
"entity": "Korrespondansepart",
97-
"id": "kp_01jh532p50epvvcjfv8xrzzwp5",
98-
...
99-
},
100-
{
101-
"entity": "Korrespondansepart",
102-
"id": "kp_01jh532p6qfhxrz1w9fdw4jjrh",
127+
"administrativEnhetObjekt": {
128+
"entity": "Enhet",
129+
"id": "enh_01jh532p50epvvcjfv8xrzzwp5",
130+
"navn": "Oslo kommune",
103131
...
104-
}]
105-
}]
132+
}
133+
}
106134
}
107135
```
108136

109137
## Client libraries
110138

111-
Client libraries for Java and TypeScript are in the works. We're also considering a .NET client library.
139+
- Java SDK: [felleslosninger/einnsyn-sdk-java](https://github.com/felleslosninger/einnsyn-sdk-java)
140+
- TypeScript SDK: [felleslosninger/einnsyn-sdk-typescript](https://github.com/felleslosninger/einnsyn-sdk-typescript)

‎typespec/einnsyn.tsp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ using TypeSpec.Http;
99

1010
@service(#{ title: "eInnsyn" })
1111
@info(#{ version: "1.0" })
12-
@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-EIN-API-KEY">)
12+
@useAuth(ApiKeyAuth<ApiKeyLocation.header, "API-KEY">)
1313
namespace EInnsyn;
1414

1515
using EInnsyn;

0 commit comments

Comments
 (0)