From 88bce914e6409d19bb95783077c8da46479bcc5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B8rhaug=2C=20Mads?= Date: Wed, 8 Jan 2020 13:28:24 +0100 Subject: [PATCH] =?UTF-8?q?Forbedringer=20OpenAPI-spec=20=20-=20Fjernet=20?= =?UTF-8?q?versjonering=20fra=20description=20=20-=20Rettet=20opp=20feil?= =?UTF-8?q?=20p=C3=A5=20versjonering=20=20-=20La=20p=C3=A5=20versjonering?= =?UTF-8?q?=20for=20alle=20tjenester=20=20-=20La=20p=C3=A5=20modell=20for?= =?UTF-8?q?=20enheter=20og=20underenheter?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- specs/enhetsregisteret.json | 193 ++++++++++++++++++++++++++++++++++-- specs/enhetsregisteret.yml | 171 ++++++++++++++++++++++++-------- 2 files changed, 311 insertions(+), 53 deletions(-) diff --git a/specs/enhetsregisteret.json b/specs/enhetsregisteret.json index 30072a8..aa8f14a 100644 --- a/specs/enhetsregisteret.json +++ b/specs/enhetsregisteret.json @@ -7,7 +7,7 @@ } ], "info": { - "description": "Teknisk beskrivelse av REST-tjenestene i Åpne Data fra Enhetsregisteret - Work in progress\n---\n\n## Ordbok\n### Enhetsregisteret\nRegister over grunndata om juridiske personer og andre enheter. Enhetsregisteret tildeler organisasjonsnummer for entydig identifisering av enheter.\n\n### Organisasjonsnummer\nNisifret nummer som entydig identifiserer enheter i Enhetsregisteret.\n\n### Enhet\nEnhet på øverste nivå i registreringsstrukturen i Enhetsregisteret. Eksempelvis enkeltpersonforetak, foreninger, selskap, sameier og andre som er registrert i Enhetsregisteret. Identifiseres med organisasjonsnummer.\n\n### Underenhet\nEnhet på laveste nivå i registreringsstrukturen i Enhetsregisteret. En underenhet kan ikke eksistere alene og har alltid knytning til en hovedenhet. Identifiseres med organisasjonsnummer.\n\n### Organisasjonsform\nOrganisasjonsform er virksomhetens formelle organisering og gir retningslinjer overfor blant annet ansvarsforhold, skatt, revisjonsplikt, rettigheter og plikter.\n\n### Næringskode\n[Næringskoder]: https://www.brreg.no/bedrift/naeringskoder/\n[Næringskoder] på brreg.no\n\n[Standard for næringsgruppering]: https://www.ssb.no/klass/klassifikasjoner/6\n[Standard for næringsgruppering]\n---\n\n## Versjonering\nDu kan velge major versjon ved å spesifisere HTTP Accept-headeren. Bruk headeren spesifisert i tabellen under. Hvis versjon ikke spesifiseres, vil man få siste versjon.\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
APIHeader
/application/vnd.enhetsregisteret.v1+json
/organisasjonsformerapplication/vnd.enhetsregisteret.organisasjonsform.v1+json
\n\n\n### Strategi\nVi skal normalt ikke bryte bakoverkompabiliteten med våre brukere. Likevel kan det være nødvendig i enkelte situasjoner, av for eksempel juridiske årsaker eller vedlikehold, å gjøre endringer som medfører et slikt brudd. Vi vil i dette tilfellet versjonere tjenesten slik at nyeste versjon vil være tilgjengelig sammen med forrige versjon.\n\n#### Dersom man ikke benytter versjonering i accept header, vil man få siste versjon.\n\nEldre versjon vil anses som utdatert/deprecated, og vil på sikt bli tatt bort. Ved behov for denne typen endringer vil vi forsøke å gi bruker god tid, og varsle om endringen i forkant. Se punkt om varsling.\n\n### Når innføres ny versjon\nVi vil innføre en ny versjon når vi introduserer en endring som påvirker bakoverkompabiliteten. Mindre endringer og patcher vil ikke medføre versjonsendring i header.\n\n### Når fjernes en versjon\nVi vil legge ut varsel/driftsmeldinger i god tid på følgende steder:\n- [Driftsmeldinger]: https://www.brreg.no/om-oss/driftsmeldinger/\n[Driftsmeldinger]\n- [RSS-feed]: https://www.brreg.no/produkter-og-tjenester/rss-feed/\n[RSS-feed].\n\nEksempel på endring som medfører versjonering:\n\n- Fjerne eller endre navn på et attributt i HTTP-responsen.\n\n- Fjerne eller endre navn på et REST endepunkt.\n\n---\n\n## Endringslogg\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
VersjonDatoEndring
1.1.014. august 2018Ny tjeneste /oppdateringer/enheter og /oppdateringer/underenheter
1.0.06. april 2018Produksjonssetting av ny åpne data tjeneste for Enhetsregisteret
\n", + "description": "Teknisk beskrivelse av REST-tjenestene i Åpne Data fra Enhetsregisteret - Work in progress\n---\n\n## Ordbok\n### Enhetsregisteret\nRegister over grunndata om juridiske personer og andre enheter. Enhetsregisteret tildeler organisasjonsnummer for entydig identifisering av enheter.\n\n### Organisasjonsnummer\nNisifret nummer som entydig identifiserer enheter i Enhetsregisteret.\n\n### Enhet\nEnhet på øverste nivå i registreringsstrukturen i Enhetsregisteret. Eksempelvis enkeltpersonforetak, foreninger, selskap, sameier og andre som er registrert i Enhetsregisteret. Identifiseres med organisasjonsnummer.\n\n### Underenhet\nEnhet på laveste nivå i registreringsstrukturen i Enhetsregisteret. En underenhet kan ikke eksistere alene og har alltid knytning til en hovedenhet. Identifiseres med organisasjonsnummer.\n\n### Organisasjonsform\nOrganisasjonsform er virksomhetens formelle organisering og gir retningslinjer overfor blant annet ansvarsforhold, skatt, revisjonsplikt, rettigheter og plikter.\n\n### Næringskode\n[Næringskoder]: https://www.brreg.no/bedrift/naeringskoder/\n[Næringskoder] på brreg.no\n\n[Standard for næringsgruppering]: https://www.ssb.no/klass/klassifikasjoner/6\n[Standard for næringsgruppering]\n---\n\n## Versjonering\nDu kan velge major versjon ved å spesifisere HTTP Accept-headeren. Bruk headeren spesifisert i tabellen under. Hvis versjon ikke spesifiseres, vil man få siste versjon.\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
APIHeader
/application/vnd.enhetsregisteret.v1+json
/organisasjonsformerapplication/vnd.brreg.enhetsregisteret.organisasjonsform.v1+json
\n\n\n### Strategi\nVi skal normalt ikke bryte bakoverkompabiliteten med våre brukere. Likevel kan det være nødvendig i enkelte situasjoner, av for eksempel juridiske årsaker eller vedlikehold, å gjøre endringer som medfører et slikt brudd. Vi vil i dette tilfellet versjonere tjenesten slik at nyeste versjon vil være tilgjengelig sammen med forrige versjon.\n\n#### Dersom man ikke benytter versjonering i accept header, vil man få siste versjon.\n\nEldre versjon vil anses som utdatert/deprecated, og vil på sikt bli tatt bort. Ved behov for denne typen endringer vil vi forsøke å gi bruker god tid, og varsle om endringen i forkant. Se punkt om varsling.\n\n### Når innføres ny versjon\nVi vil innføre en ny versjon når vi introduserer en endring som påvirker bakoverkompabiliteten. Mindre endringer og patcher vil ikke medføre versjonsendring i header.\n\n### Når fjernes en versjon\nVi vil legge ut varsel/driftsmeldinger i god tid på følgende steder:\n- [Driftsmeldinger]: https://www.brreg.no/om-oss/driftsmeldinger/\n[Driftsmeldinger]\n- [RSS-feed]: https://www.brreg.no/produkter-og-tjenester/rss-feed/\n[RSS-feed].\n\nEksempel på endring som medfører versjonering:\n\n- Fjerne eller endre navn på et attributt i HTTP-responsen.\n\n- Fjerne eller endre navn på et REST endepunkt.\n\n---\n", "version": "1.0.0", "title": "Åpne Data fra Enhetsregisteret - API Dokumentasjon", "contact": { @@ -32,6 +32,11 @@ "schema": { "type": "string" } + }, + "application/vnd.brreg.enhetsregisteret.v1+json": { + "schema": { + "type": "string" + } } } }, @@ -370,7 +375,12 @@ "content": { "application/json": { "schema": { - "type": "string" + "$ref": "#/components/schemas/_Enheter" + } + }, + "application/vnd.brreg.enhetsregisteret.enhet.v1+json": { + "schema": { + "$ref": "#/components/schemas/_Enheter" } } } @@ -408,7 +418,7 @@ "$ref": "#/components/schemas/Enhet" } }, - "application/vnd.enhetsregisteret.enhet.v1+json": { + "application/vnd.brreg.enhetsregisteret.enhet.v1+json": { "schema": { "$ref": "#/components/schemas/Enhet" } @@ -715,7 +725,12 @@ "content": { "application/json": { "schema": { - "type": "string" + "$ref": "#/components/schemas/_Underenheter" + } + }, + "application/vnd.brreg.enhetsregisteret.underenhet.v1+json": { + "schema": { + "$ref": "#/components/schemas/_Underenheter" } } } @@ -747,7 +762,12 @@ "content": { "application/json": { "schema": { - "type": "string" + "$ref": "#/components/schemas/Underenhet" + } + }, + "application/vnd.brreg.enhetsregisteret.underenhet.v1+json": { + "schema": { + "$ref": "#/components/schemas/Underenhet" } } } @@ -802,6 +822,11 @@ "description": "Oppdateringer på enheter fra Enhetsregisteret", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/Enhet" + } + }, + "application/vnd.brreg.enhetsregisteret.oppdatering.enhet.v1+json": { "schema": { "type": "string" } @@ -852,6 +877,11 @@ "description": "Oppdateringer på underenheter fra Enhetsregisteret", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/Enhet" + } + }, + "application/vnd.brreg.enhetsregisteret.oppdatering.underenhet.v1+json": { "schema": { "type": "string" } @@ -877,7 +907,7 @@ "$ref": "#/components/schemas/_Organisasjonsformer" } }, - "application/vnd.enhetsregisteret.organisasjonsform.v1+json": { + "application/vnd.brreg.enhetsregisteret.organisasjonsform.v1+json": { "schema": { "$ref": "#/components/schemas/_Organisasjonsformer" } @@ -920,7 +950,7 @@ "$ref": "#/components/schemas/Organisasjonsform" } }, - "application/vnd.enhetsregisteret.organisasjonsform.v1+json": { + "application/vnd.brreg.enhetsregisteret.organisasjonsform.v1+json": { "schema": { "$ref": "#/components/schemas/Organisasjonsform" } @@ -946,7 +976,12 @@ "content": { "application/json": { "schema": { - "type": "string" + "$ref": "#/components/schemas/_Organisasjonsformer" + } + }, + "application/vnd.brreg.enhetsregisteret.organisasjonsform.v1+json": { + "schema": { + "$ref": "#/components/schemas/_Organisasjonsformer" } } } @@ -967,7 +1002,12 @@ "content": { "application/json": { "schema": { - "type": "string" + "$ref": "#/components/schemas/_Organisasjonsformer" + } + }, + "application/vnd.brreg.enhetsregisteret.organisasjonsform.v1+json": { + "schema": { + "$ref": "#/components/schemas/_Organisasjonsformer" } } } @@ -981,6 +1021,52 @@ }, "components": { "schemas": { + "Underenhet": { + "properties": { + "organisasjonsnummer": { + "type": "string" + }, + "navn": { + "type": "string" + }, + "organisasjonsform": { + "$ref": "#/components/schemas/Organisasjonsform" + }, + "postadresse": { + "$ref": "#/components/schemas/Adresse" + }, + "registreringsdatoEnhetsregisteret": { + "type": "string" + }, + "registrertIMvaregisteret": { + "type": "boolean" + }, + "naeringskode1": { + "$ref": "#/components/schemas/Naeringskode" + }, + "naeringskode2": { + "$ref": "#/components/schemas/Naeringskode" + }, + "naeringskode3": { + "$ref": "#/components/schemas/Naeringskode" + }, + "antallAnsatte": { + "type": "integer" + }, + "overordnetEnhet": { + "type": "string" + }, + "oppstartsdato": { + "type": "string" + }, + "beliggenhetsadresse": { + "$ref": "#/components/schemas/Adresse" + }, + "_links": { + "$ref": "#/components/schemas/_Links" + } + } + }, "Enhet": { "properties": { "organisasjonsnummer": { @@ -992,12 +1078,24 @@ "organisasjonsform": { "$ref": "#/components/schemas/Organisasjonsform" }, + "hjemmeside": { + "type": "string" + }, + "postadresse": { + "$ref": "#/components/schemas/Adresse" + }, "registreringsdatoEnhetsregisteret": { "type": "string" }, "registrertIMvaregisteret": { "type": "boolean" }, + "frivilligMvaRegistrertBeskrivelser": { + "type": "array", + "items": { + "type": "string" + } + }, "naeringskode1": { "$ref": "#/components/schemas/Naeringskode" }, @@ -1010,6 +1108,9 @@ "antallAnsatte": { "type": "integer" }, + "forretningsadresse": { + "$ref": "#/components/schemas/Adresse" + }, "stiftelsedato": { "type": "string" }, @@ -1041,7 +1142,35 @@ "type": "string" }, "_links": { - "$ref": "#/components/schemas/Self" + "$ref": "#/components/schemas/_Links" + } + } + }, + "Adresse": { + "properties": { + "land": { + "type": "string" + }, + "landkode": { + "type": "string" + }, + "postnummer": { + "type": "string" + }, + "poststed": { + "type": "string" + }, + "adresse": { + "type": "array", + "items": { + "type": "string" + } + }, + "kommune": { + "type": "string" + }, + "kommunenummer": { + "type": "string" } } }, @@ -1065,6 +1194,40 @@ } } }, + "_Enheter": { + "properties": { + "embedded": { + "$ref": "#/components/schemas/Enheter" + } + } + }, + "Enheter": { + "properties": { + "enheter": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Enhet" + } + } + } + }, + "_Underenheter": { + "properties": { + "embedded": { + "$ref": "#/components/schemas/Underenheter" + } + } + }, + "Underenheter": { + "properties": { + "enheter": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Underenhet" + } + } + } + }, "_Organisasjonsformer": { "properties": { "embedded": { @@ -1102,6 +1265,16 @@ } } }, + "_Links": { + "properties": { + "self": { + "$ref": "#/components/schemas/Href" + }, + "overordnetEnhet": { + "$ref": "#/components/schemas/Href" + } + } + }, "Href": { "properties": { "href": { diff --git a/specs/enhetsregisteret.yml b/specs/enhetsregisteret.yml index 5fa70c5..88278c3 100644 --- a/specs/enhetsregisteret.yml +++ b/specs/enhetsregisteret.yml @@ -1,6 +1,6 @@ openapi: 3.0.0 servers: - - url: https://data.brreg.no/enhetsregisteret/api + - url: 'https://data.brreg.no/enhetsregisteret/api' description: Produksjon info: description: | @@ -47,7 +47,7 @@ info: /organisasjonsformer - application/vnd.enhetsregisteret.organisasjonsform.v1+json + application/vnd.brreg.enhetsregisteret.organisasjonsform.v1+json @@ -78,37 +78,14 @@ info: --- - ## Endringslogg - - - - - - - - - - - - - - - - - - - - -
VersjonDatoEndring
1.1.014. august 2018Ny tjeneste /oppdateringer/enheter og /oppdateringer/underenheter
1.0.06. april 2018Produksjonssetting av ny åpne data tjeneste for Enhetsregisteret
- - version: "1.0.0" + version: 1.0.0 title: Åpne Data fra Enhetsregisteret - API Dokumentasjon contact: name: Forenkling og Brukerdialog hos Brønnøysundregistrene email: opendata@brreg.no license: name: Norsk lisens for offentlige data (NLOD) - url: https://data.norge.no/nlod/no/ + url: 'https://data.norge.no/nlod/no/' paths: /: get: @@ -121,6 +98,9 @@ paths: application/json: schema: type: string + application/vnd.brreg.enhetsregisteret.v1+json: + schema: + type: string default: description: Udefinert feil /enheter: @@ -346,12 +326,15 @@ paths: content: application/json: schema: - type: string + $ref: '#/components/schemas/_Enheter' + application/vnd.brreg.enhetsregisteret.enhet.v1+json: + schema: + $ref: '#/components/schemas/_Enheter' '400': description: Ugyldig forespørsel default: description: Udefinert feil - /enheter/{organisasjonsnummer}: + '/enheter/{organisasjonsnummer}': parameters: - name: organisasjonsnummer in: path @@ -369,7 +352,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Enhet' - application/vnd.enhetsregisteret.enhet.v1+json: + application/vnd.brreg.enhetsregisteret.enhet.v1+json: schema: $ref: '#/components/schemas/Enhet' '404': @@ -575,10 +558,13 @@ paths: content: application/json: schema: - type: string + $ref: '#/components/schemas/_Underenheter' + application/vnd.brreg.enhetsregisteret.underenhet.v1+json: + schema: + $ref: '#/components/schemas/_Underenheter' default: description: Udefinert feil - /underenheter/{organisasjonsnummer}: + '/underenheter/{organisasjonsnummer}': parameters: - name: organisasjonsnummer in: path @@ -595,7 +581,10 @@ paths: content: application/json: schema: - type: string + $ref: '#/components/schemas/Underenhet' + application/vnd.brreg.enhetsregisteret.underenhet.v1+json: + schema: + $ref: '#/components/schemas/Underenhet' '404': description: Underenhet finnes ikke '410': @@ -606,7 +595,7 @@ paths: parameters: - name: dato in: query - description: "Tidligste tidsstempel for når enheten ble oppdatert. På format Datetime (ISO-8601): yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" + description: 'Tidligste tidsstempel for når enheten ble oppdatert. På format Datetime (ISO-8601): yyyy-MM-dd''T''HH:mm:ss.SSS''Z''' required: false schema: type: string @@ -627,9 +616,12 @@ paths: description: Hent oppdateringer på enheter responses: '200': - description: Oppdateringer på enheter fra Enhetsregisteret + description: Oppdateringer på enheter fra Enhetsregisteret content: application/json: + schema: + $ref: '#/components/schemas/Enhet' + application/vnd.brreg.enhetsregisteret.oppdatering.enhet.v1+json: schema: type: string default: @@ -638,7 +630,7 @@ paths: parameters: - name: dato in: query - description: "Tidligste tidsstempel for når enheten ble oppdatert. På format Datetime (ISO-8601): yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" + description: 'Tidligste tidsstempel for når enheten ble oppdatert. På format Datetime (ISO-8601): yyyy-MM-dd''T''HH:mm:ss.SSS''Z''' required: false schema: type: string @@ -659,9 +651,12 @@ paths: description: Hent oppdateringer på underenheter responses: '200': - description: Oppdateringer på underenheter fra Enhetsregisteret + description: Oppdateringer på underenheter fra Enhetsregisteret content: application/json: + schema: + $ref: '#/components/schemas/Enhet' + application/vnd.brreg.enhetsregisteret.oppdatering.underenhet.v1+json: schema: type: string default: @@ -677,12 +672,12 @@ paths: application/json: schema: $ref: '#/components/schemas/_Organisasjonsformer' - application/vnd.enhetsregisteret.organisasjonsform.v1+json: + application/vnd.brreg.enhetsregisteret.organisasjonsform.v1+json: schema: $ref: '#/components/schemas/_Organisasjonsformer' default: description: Udefinert feil - /organisasjonsformer/{orgformKode}: + '/organisasjonsformer/{orgformKode}': parameters: - name: orgformKode in: path @@ -704,7 +699,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Organisasjonsform' - application/vnd.enhetsregisteret.organisasjonsform.v1+json: + application/vnd.brreg.enhetsregisteret.organisasjonsform.v1+json: schema: $ref: '#/components/schemas/Organisasjonsform' '404': @@ -721,7 +716,10 @@ paths: content: application/json: schema: - type: string + $ref: '#/components/schemas/_Organisasjonsformer' + application/vnd.brreg.enhetsregisteret.organisasjonsform.v1+json: + schema: + $ref: '#/components/schemas/_Organisasjonsformer' default: description: Udefinert feil /organisasjonsformer/underenheter: @@ -734,11 +732,44 @@ paths: content: application/json: schema: - type: string + $ref: '#/components/schemas/_Organisasjonsformer' + application/vnd.brreg.enhetsregisteret.organisasjonsform.v1+json: + schema: + $ref: '#/components/schemas/_Organisasjonsformer' default: description: Udefinert feil components: schemas: + Underenhet: + properties: + organisasjonsnummer: + type: string + navn: + type: string + organisasjonsform: + $ref: '#/components/schemas/Organisasjonsform' + postadresse: + $ref: '#/components/schemas/Adresse' + registreringsdatoEnhetsregisteret: + type: string + registrertIMvaregisteret: + type: boolean + naeringskode1: + $ref: '#/components/schemas/Naeringskode' + naeringskode2: + $ref: '#/components/schemas/Naeringskode' + naeringskode3: + $ref: '#/components/schemas/Naeringskode' + antallAnsatte: + type: integer + overordnetEnhet: + type: string + oppstartsdato: + type: string + beliggenhetsadresse: + $ref: '#/components/schemas/Adresse' + _links: + $ref: '#/components/schemas/_Links' Enhet: properties: organisasjonsnummer: @@ -747,10 +778,18 @@ components: type: string organisasjonsform: $ref: '#/components/schemas/Organisasjonsform' + hjemmeside: + type: string + postadresse: + $ref: '#/components/schemas/Adresse' registreringsdatoEnhetsregisteret: type: string registrertIMvaregisteret: type: boolean + frivilligMvaRegistrertBeskrivelser: + type: array + items: + type: string naeringskode1: $ref: '#/components/schemas/Naeringskode' naeringskode2: @@ -759,6 +798,8 @@ components: $ref: '#/components/schemas/Naeringskode' antallAnsatte: type: integer + forretningsadresse: + $ref: '#/components/schemas/Adresse' stiftelsedato: type: string institusjonellSektorkode: @@ -780,7 +821,25 @@ components: maalform: type: string _links: - $ref: '#/components/schemas/Self' + $ref: '#/components/schemas/_Links' + Adresse: + properties: + land: + type: string + landkode: + type: string + postnummer: + type: string + poststed: + type: string + adresse: + type: array + items: + type: string + kommune: + type: string + kommunenummer: + type: string Naeringskode: properties: kode: @@ -793,6 +852,26 @@ components: type: string beskrivelse: type: string + _Enheter: + properties: + embedded: + $ref: '#/components/schemas/Enheter' + Enheter: + properties: + enheter: + type: array + items: + $ref: '#/components/schemas/Enhet' + _Underenheter: + properties: + embedded: + $ref: '#/components/schemas/Underenheter' + Underenheter: + properties: + enheter: + type: array + items: + $ref: '#/components/schemas/Underenhet' _Organisasjonsformer: properties: embedded: @@ -815,6 +894,12 @@ components: properties: self: $ref: '#/components/schemas/Href' + _Links: + properties: + self: + $ref: '#/components/schemas/Href' + overordnetEnhet: + $ref: '#/components/schemas/Href' Href: properties: href: