Generell information
Detta API baseras på standarden JSON API och är specificerat enligt OpenAPI 3.0.3 .
Specifikationen för Adressbokens API för nedladdning: sdk-addressbook-v1.1.openapi.yaml
Rapport över kompatibilitet mellan Diggs och Ineras implementationer av API: API Kompatibilitet: Digg vs Inera
Endast läsoperationer är tillgängliga via denna version av Adressbok API, ingen auktorisation krävs för att utföra dessa läsoperationer.
Produktionsmiljöer och URL:er
| Miljö | URL UI | Bas-URL API | Exempel: lista alla adresser |
|---|---|---|---|
|
SDK Produktionsmiljö |
|||
|
SDK Acceptansmiljö |
|||
|
SDK Öppen testmiljö |
License & copyright
This API is licensed under a MIT license. https://spdx.org/licenses/MIT.html
This documentation is licensed under a CC4.0-BY-SA license. https://creativecommons.org/licenses/by-sa/4.0/
Security Considerations
Data usage and XSS
A note on security and XSS (Cross-Site Scripting) attacks.
-
The API makes no assumptions about the client environment.
-
It is primarily the responsibility of the consumer of the API to ensure that the data returned by the API (represented as JSON) is safe to use in the IT environment of the client.
-
For instance; if the data is used by a browser based (web) client -measures should be taken to ensure that sensitive characters are properly escaped.
-
The API do however enforce some formatting / validation of input data. Only a subset of characters are allowed in text fields, see documentation of individual fields below. Notably, the web client sensitive characters “<“ and “>” are not allowed to be entered into the system.
Cross-Origin Resource Sharing
No cross-origin sharing is allowed and no CORS headers are set. This means that the API can only be accessed from the same origin.
1. Endpoints
Dokumentationen nedan genereras direkt från API specifikation och källkod (på engelska).
Mappning av koncept mellan informationsmodell och API:
| Resurs i API | Benämning infomodell | Svensk översättning | Beskrivning |
|---|---|---|---|
|
Addresses |
Functional Address |
Funktionsadress |
(Virtuell) verksamhetsfunktion inom organisation. Minsta adresserbara enhet för ett meddelande inom SDK. |
|
Organizations |
Organization |
Organisation |
Användarorganisation inom SDK. En organisation har en eller flera funktionsadresser. |
|
Codesystems |
Codesystems |
Kodverk |
Kodverk och koder som används inom SDK. Ett kodverk har en eller flera koder. |
|
Codes |
Codes |
Koder |
Kodverk och koder som används inom SDK. Ett kodverk har en eller flera koder. |
1.1. Address
All GET operations documented below expect the Export functionality returns active Addresses only. Active Addresses are those with Activation Date after - and/or Deactivation Date before the current date. The Export functionality (which requires authentication) will export also inactive addresses.
All listing operations ("Search" and "Get All" with/without filters) are paged (max 25 results per page).
1.1.1. Your GET endpoint
| Method |
GET |
| Path |
|
| Operation Id |
getAddressesForOrganization |
Lists addresses for an organization. Responses are paged. Returns 200 is any addresses is found Returns 204 is no addresses for the organization match the filter criterias, contains a JSONAPIAddressResponse with an empty data: [] Returns 400 is any of the query parameters fails validation Returns 404 is the organization does not exist
Path Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
organizationResourceIdentifier |
A unique and persistent identifier ,,set by the server,, in the form of a ,,UUID,,. This value has no real-world reference or business meaning, i.e. it is a technical surrogate identifier. Any changes by the client to this field will be ignored. |
X |
null |
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Query Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
filter[name] |
Filters by name |
- |
null |
|
|
filter[categories] |
Filters addresses by category (a.k.a "tags"). |
- |
null |
|
|
filter[codes.coding.code] |
Filters by Codes. Note: codes (and code systems) used by SDK is defined in "SDK Kodverksregister" (SDK Code System Registry). |
- |
null |
|
|
filter[regionCode.coding.code] |
Applies geographic filtering on ,,Swedish Region code ("Länskod"),,. Comma-separated list if many. |
- |
null |
|
|
filter[municipalityCode.coding.code] |
Applies geographic filtering on ,,Swedish Municipality code ("Kommunkod"),,. Comma-separated list if many. |
- |
null |
|
|
filter[excludeNationalCoverage] |
Excludes addresses with nationwide coverage (i.e. Addresses with no Region- and Municipality codes set). Defaults to false. |
- |
false |
|
|
filter[matchAllCodes] |
Controls the filtering logic for codes - used in conjunction with filter[codes.coding.code]. If "true" only Addresses that contain at least ALL the submitted codes will be fetched (if omitted or set to "false" - the default behavior of matching at least ONE submitted code will be applied). |
- |
false |
|
|
page[number] |
Controls what subset (a.k.a "page") of the whole available set/collection should be returned. |
- |
0 |
|
|
page[size] |
Limits the number of resources returned in the response. The server will default to 25 for this value if omitted. A client can get fewer results by setting a smaller value. If set to larger than 25, the server will ignore this parameter and use the default (25). |
- |
25 |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
204 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
400 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
404 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
1.1.2. Get addresses with filtering
| Method |
GET |
| Path |
|
| Operation Id |
getAllAddresses |
Lists Addresses and applies filtering. Responses are paged, default page size is 25 results per page, see pagination.
Error handling
Returns 200 if any addresses is found
Returns 204 if no addresses match the filter criterias, contains a JSONAPIAddressResponse with an empty data: []
Returns 400 if any of the query parameters fails validation Returns 404 if the address is uniquely identified (filter[organization.participantIdentifier] + filter[identifier]) but not found
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Query Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
q |
The search term to use for free text search |
- |
null |
|
|
filter[name] |
Filters by name |
- |
null |
|
|
filter[organization.participantIdentifier] |
Filters addresses by Participant Identifier of the parent Organization. |
- |
null |
|
|
filter[organization.type] |
Filters addresses by "Type" of parent Organization. |
- |
null |
|
|
filter[identifier] |
Filters addresses by its identifier (the unique function address used for message routing). |
- |
null |
|
|
filter[unitName] |
Filters addresses by its unit name. |
- |
null |
|
|
filter[categories] |
Filters addresses by category (a.k.a "tags"). |
- |
null |
|
|
filter[codes.coding.code] |
Filters by Codes. Note: codes (and code systems) used by SDK is defined in "SDK Kodverksregister" (SDK Code System Registry). |
- |
null |
|
|
filter[codes.coding.system] |
Filters by Code Systems. May be used in combination with function codes, to conduct fully qualified code searches. Note: Code System filter will apply to all Codes in the filter expression. |
- |
null |
|
|
filter[regionCode.coding.code] |
Applies geographic filtering on ,,Swedish Region code ("Länskod"),,. Comma-separated list if many. |
- |
null |
|
|
filter[municipalityCode.coding.code] |
Applies geographic filtering on ,,Swedish Municipality code ("Kommunkod"),,. Comma-separated list if many. |
- |
null |
|
|
filter[excludeNationalCoverage] |
Excludes addresses with nationwide coverage (i.e. Addresses with no Region- and Municipality codes set). Defaults to false. |
- |
false |
|
|
filter[matchAllCodes] |
Controls the filtering logic for codes - used in conjunction with filter[codes.coding.code]. If "true" only Addresses that contain at least ALL the submitted codes will be fetched (if omitted or set to "false" - the default behavior of matching at least ONE submitted code will be applied). |
- |
false |
|
|
caseSensitive |
An optional string value ("true" |
"false") indicating if distinction between uppercase and lowercase letters should be active. Inactive ("false") by default. NB! Only applies to text-attribute filters |
- |
false |
|
include |
Request parameter to allow the client to customize which related resources should be returned. Valid value(s): "parent". |
- |
null |
|
|
/parent/ |
page[number] |
Controls what subset (a.k.a "page") of the whole available set/collection should be returned. |
- |
0 |
|
page[size] |
Limits the number of resources returned in the response. The server will default to 25 for this value if omitted. A client can get fewer results by setting a smaller value. If set to larger than 25, the server will ignore this parameter and use the default (25). |
- |
25 |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
204 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
400 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
404 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
1.1.3. Get all categories for all addresses
| Method |
GET |
| Path |
|
| Operation Id |
getAllCategories |
Retrieves all addresses categories (search tags).
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
OK |
|
|
400 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
404 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
1.1.4. Get one address
| Method |
GET |
| Path |
|
| Operation Id |
getOneAddress |
Retrieves one address by Resource Identifier. Error handling Returns 200 if the address is found Returns 404 if the address does not exist
Path Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
addressResourceIdentifier |
A unique and persistent identifier ,,set by the server,, in the form of a ,,UUID,, This value has no real-world reference or business meaning, i.e. it is a technical surrogate identifier. Any changes by the client to this field will be ignored. |
X |
null |
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Query Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
include |
Request parameter to allow the client to customize which related resources should be returned. Valid value(s): "parent". |
- |
null |
/parent/ |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
400 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
404 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
1.1.5. Full text search of addresses
| Method |
GET |
| Path |
|
| Operation Id |
searchForAddresses |
Full text search of text attributes of Addresses by the given search term, and applies filtering. Responses are ordered by best match to search term. Responses are paged, default page size is 25 results per page, see pagination. Error handling Returns 200 if any addresses is found Returns 204 if no addresses match the search / filter criterias, contains a JSONAPIAddressResponse with an empty data: [] Returns 400 if any of the query parameters fails validation
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Query Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
q |
The search term to use for free text search |
- |
null |
|
|
filter[categories] |
Filters addresses by category (a.k.a "tags"). |
- |
null |
|
|
filter[codes.coding.code] |
Filters by Codes. Note: codes (and code systems) used by SDK is defined in "SDK Kodverksregister" (SDK Code System Registry). |
- |
null |
|
|
filter[codes.coding.system] |
Filters by Code Systems. May be used in combination with function codes, to conduct fully qualified code searches. Note: Code System filter will apply to all Codes in the filter expression. |
- |
null |
|
|
filter[regionCode.coding.code] |
Applies geographic filtering on ,,Swedish Region code ("Länskod"),,. Comma-separated list if many. |
- |
null |
|
|
filter[municipalityCode.coding.code] |
Applies geographic filtering on ,,Swedish Municipality code ("Kommunkod"),,. Comma-separated list if many. |
- |
null |
|
|
filter[excludeNationalCoverage] |
Excludes addresses with nationwide coverage (i.e. Addresses with no Region- and Municipality codes set). Defaults to false. |
- |
false |
|
|
filter[matchAllCodes] |
Controls the filtering logic for codes - used in conjunction with filter[codes.coding.code]. If "true" only Addresses that contain at least ALL the submitted codes will be fetched (if omitted or set to "false" - the default behavior of matching at least ONE submitted code will be applied). |
- |
false |
|
|
caseSensitive |
An optional string value ("true" |
"false") indicating if distinction between uppercase and lowercase letters should be active. Inactive ("false") by default. NB! Only applies to text-attribute filters |
- |
false |
|
include |
Request parameter to allow the client to customize which related resources should be returned. Valid value(s): "parent". |
- |
null |
|
|
/parent/ |
page[number] |
Controls what subset (a.k.a "page") of the whole available set/collection should be returned. |
- |
0 |
|
page[size] |
Limits the number of resources returned in the response. The server will default to 25 for this value if omitted. A client can get fewer results by setting a smaller value. If set to larger than 25, the server will ignore this parameter and use the default (25). |
- |
25 |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
204 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
400 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
1.2. Code
1.2.1. Your GET endpoint
| Method |
GET |
| Path |
|
| Operation Id |
getAllCodesForCodesystem |
Get all codes for one codesystem Returns 200 if any codes is found Returns 204 if no codes for the codesystem exists, contains a JSONAPICodeResponse with an empty data: [] Returns 404 if the codesystem does not exist
Path Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
identifier |
A unique and persistent Code System identifier in the form of an ,,Object Identifier (OID),. |
X |
null |
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
204 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
404 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
1.2.2. Your GET endpoint
| Method |
GET |
| Path |
|
| Operation Id |
getOneCodeForCodesystem |
Get one code for one codesystem Returns 200 if the code is found Returns 204 is no code for the codesystem match the code, contains a JSONAPICodeResponse (FIXME: check if this is correct) with an empty data: [] Returns 404 if the codesystem or code does not exist
Path Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
identifier |
A unique and persistent Code System identifier in the form of an ,,Object Identifier (OID),,. |
X |
null |
|
|
code |
A unique code identifier - constructed from the concatenation of "{codeSystemIdentifier}-{code value}". |
X |
null |
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
204 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
400 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
404 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
1.3. CodeSystem
1.3.1. Your GET endpoint
| Method |
GET |
| Path |
|
| Operation Id |
getAllCodesystems |
Lists Code Systems. Responses are paged. Returns 200 if any code system is found Returns 204 if no code system match the filter criterias, contains a JSONAPICodeSystemResponse with an empty data: [] Returns 400 if any of the query parameters fails validation Returns 404 if the code system is uniquely identified (filter[id]) but not found
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Query Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
filter[name] |
Filters by name |
- |
null |
|
|
filter[id] |
The resource identifier(s) to filter by. |
- |
null |
|
|
filter[systemType] |
Filter by system type |
- |
null |
|
|
page[number] |
Controls what subset (a.k.a "page") of the whole available set/collection should be returned. |
- |
0 |
|
|
page[size] |
Limits the number of resources returned in the response. The server will default to 25 for this value if omitted. A client can get fewer results by setting a smaller value. If set to larger than 25, the server will ignore this parameter and use the default (25). |
- |
25 |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
400 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
1.3.2. Your GET endpoint
| Method |
GET |
| Path |
|
| Operation Id |
getOneCodesystem |
Retrieves one Code System by system identifier. Returns 200 if the code system is found Returns 404 if the code system does not exist
Path Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
identifier |
A unique and persistent Code System identifier in the form of an ,,Object Identifier (OID),,. |
X |
null |
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
400 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
404 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
1.4. Organization
1.4.1. Your GET endpoint
| Method |
GET |
| Path |
|
| Operation Id |
getAllOrganizations |
Retrieves one Organization by Resource Identifier, this value has no real-world reference or business meaning, i.e. it is a technical surrogate identifier. Returns 200 if any organizations is found Returns 204 if no organizations match the filter criterias, contains a JSONAPIOrganizationResponse with an empty data: [] Returns 400 if any of the query parameters fails validation Returns 404 if the organization is uniquely identified (filter[id] or filter[participantIdentifier] + filter[organizationNumber]) but not found
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Query Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
q |
The search term to use for free text search |
- |
null |
|
|
filter[name] |
Filters by name |
- |
null |
|
|
filter[id] |
The resource identifier(s) to filter by. |
- |
null |
|
|
filter[participantIdentifier] |
Filters organizations by Participant Identifier. |
- |
null |
|
|
filter[organizationNumber] |
Filter by organization number |
- |
null |
|
|
filter[type] |
Filters organizations by "Type". |
- |
null |
|
|
filter[regionCode.coding.code] |
Applies geographic filtering on ,,Swedish Region code ("Länskod"),,. Comma-separated list if many. |
- |
null |
|
|
filter[municipalityCode.coding.code] |
Applies geographic filtering on ,,Swedish Municipality code ("Kommunkod"),,. Comma-separated list if many. |
- |
null |
|
|
filter[managementCode.coding.code] |
Filter by management code. Comma-separated list if many. |
- |
null |
|
|
filter[excludeNationalCoverage] |
Excludes addresses with nationwide coverage (i.e. Addresses with no Region- and Municipality codes set). Defaults to false. |
- |
false |
|
|
caseSensitive |
An optional string value ("true" |
"false") indicating if distinction between uppercase and lowercase letters should be active. Inactive ("false") by default. NB! Only applies to text-attribute filters |
- |
false |
|
include |
Request parameter to allow the client to customize which related resources should be returned. Valid value(s): "parent". |
- |
null |
|
|
/parent/ |
page[number] |
Controls what subset (a.k.a "page") of the whole available set/collection should be returned. |
- |
0 |
|
page[size] |
Limits the number of resources returned in the response. The server will default to 25 for this value if omitted. A client can get fewer results by setting a smaller value. If set to larger than 25, the server will ignore this parameter and use the default (25). |
- |
25 |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
204 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
400 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
404 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
1.4.2. GET /organizations/{organizationResourceIdentifier}
| Method |
GET |
| Path |
|
| Operation Id |
getOneOrganization |
Retrieves one Organization by Resource Identifier, this value has no real-world reference or business meaning, i.e. it is a technical surrogate identifier. Returns 200 if the organization is found Returns 404 if the organization does not exist
Path Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
organizationResourceIdentifier |
A unique and persistent identifier ,,set by the server,, in the form of a ,,UUID,,. This value has no real-world reference or business meaning, i.e. it is a technical surrogate identifier. Any changes by the client to this field will be ignored. |
X |
null |
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Query Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
include |
Request parameter to allow the client to customize which related resources should be returned. Valid value(s): "parent". |
- |
null |
/parent/ |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
204 |
No Content |
<<>> |
|
400 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
404 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
1.4.3. Full text search of organizations
| Method |
GET |
| Path |
|
| Operation Id |
searchForOrganizations |
Full text search of text attributes of organizations by the given search term, and applies filtering. Responses are ordered by best match to search term. Responses are paged, default page size is 25 results per page, see pagination. Error handling Returns 200 if any organizations is found Returns 204 if no organizations match the search / filter criterias, contains a JSONAPIOrganizationResponse with an empty data: [] Returns 400 if any of the query parameters fails validation
Header Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
Accept-Language |
Indicates the natural language and locale that the client prefers |
- |
sv-SE |
Query Parameters
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
|
q |
The search term to use for free text search |
- |
null |
|
|
caseSensitive |
An optional string value ("true" |
"false") indicating if distinction between uppercase and lowercase letters should be active. Inactive ("false") by default. NB! Only applies to text-attribute filters |
- |
false |
|
filter[type] |
Filters organizations by "Type". |
- |
null |
|
|
include |
Request parameter to allow the client to customize which related resources should be returned. Valid value(s): "parent". |
- |
null |
|
|
/parent/ |
page[number] |
Controls what subset (a.k.a "page") of the whole available set/collection should be returned. |
- |
0 |
|
page[size] |
Limits the number of resources returned in the response. The server will default to 25 for this value if omitted. A client can get fewer results by setting a smaller value. If set to larger than 25, the server will ignore this parameter and use the default (25). |
- |
25 |
Return Type
Content Type
-
application/json
Responses
| Code | Message | Datatype |
|---|---|---|
|
200 |
A JSON object MUST be at the root of every JSON:API request and response document containing data. This object defines a document’s “top level”. |
|
|
204 |
No Content |
<<>> |
|
400 |
4xx Client error Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document |
|
|
500 |
Internal Server Error |
<<>> |
Samples
2. Models
2.1. Address
Represents a reachable adress within an organization
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
|
identifier |
String |
|||
name |
String |
|||
|
unitName |
String |
|||
|
description |
String |
|||
|
activatedAt |
Date |
date-time |
||
|
deactivatedAt |
Date |
date-time |
||
|
updatedAt |
Date |
date-time |
||
|
categories |
List of [string] |
|||
codes |
List of CodeWrapper |
|||
|
municipalityCode |
List of CodeWrapper |
|||
|
regionCode |
List of CodeWrapper |
2.2. AddressCategoriesResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
|
categories |
List of [string] |
2.3. Code
Codes
A list of Codes defined by a set of decided Terminology Systems. Codes are applied to a Functional Address to facilitate systematic searching. Search codes may express the "business function" of the Address (Swedish: "sökkod eller funktionskod") and / or organizational structure of the Address (Swedish: "strukturkod").
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
code |
X |
String |
Symbol in syntax defined by the system. |
|
|
displayName |
String |
Representation defined by the system. If missing {@link #originalText} should be used. |
||
|
originalText |
X |
String |
A human language representation of the concept as seen/selected/uttered by the user who entered the data and/or which represents the intended meaning of the user. |
|
|
additionalInfo |
String |
Additional information, a human-friendly description to determine the applicability of the code. |
2.4. CodeSystem
CodeSystem
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
system |
X |
String |
A unique identifier for the code system (business identifier) usually an OID. |
|
name |
X |
String |
Name for this code system. |
|
version |
X |
String |
The version for this code system. |
|
|
alternateName |
String |
An alternate name for this code system. |
||
|
description |
String |
A clear text description of the code system. |
||
|
systemType |
X |
String |
Defines the purpose of the code system. Must be one of [SEARCH, STRUCTURE, GEO, SYSTEM, OTHER]. |
Enum: SEARCH, STRUCTURE, GEO, SYSTEM, OTHER, |
|
createdAt |
Date |
The date and time when this code system was added to the system. |
date-time |
|
|
updatedAt |
Date |
The date and time when this code system was updated (e.g. a change of metadata). |
date-time |
|
String |
The email address to the organization maintaining this code system. |
|||
url |
String |
The homepage of this code system. |
2.5. CodeSystemWrapper
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
system |
String |
|||
name |
String |
|||
version |
String |
2.6. CodeWrapper
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
text |
String |
|||
coding |
CodeWrapperCoding |
2.7. CodeWrapperCoding
CodeWrapperCoding
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
system |
String |
|||
code |
String |
|||
|
displayText |
String |
|||
|
additionalInfo |
String |
2.8. JSONAPIAddressResourceObject
"Resource objects” appear in a JSON:API document to represent resources.
A resource object MUST contain at least the following top-level members: * type * id
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
type |
X |
String |
||
id |
String |
|||
|
attributes |
Address |
|||
|
relationships |
JSONAPIParentRelationshipObject |
|||
links |
JSONAPISelfLinks |
2.9. JSONAPIAddressResponse
JSONAPIAddressResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
meta |
JSONAPIMeta |
|||
links |
JSONAPIPaginationLinks |
|||
data |
X |
List of JSONAPIAddressResourceObject |
||
|
included |
2.10. JSONAPICodeResourceObject
"Resource objects” appear in a JSON:API document to represent resources.
A resource object MUST contain at least the following top-level members: * type * id
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
type |
X |
String |
||
id |
String |
|||
|
attributes |
Code |
2.11. JSONAPICodeResponse
JSONAPICodeResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
meta |
JSONAPIMeta |
|||
links |
JSONAPIPaginationLinks |
|||
data |
X |
List of JSONAPICodeResourceObject |
2.12. JSONAPICodeSystemResourceObject
"Resource objects” appear in a JSON:API document to represent resources.
A resource object MUST contain at least the following top-level members: * type * id
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
type |
X |
String |
||
id |
String |
|||
|
attributes |
CodeSystem |
2.13. JSONAPICodeSystemResponse
JSONAPICodeSystemResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
meta |
JSONAPIMeta |
|||
links |
JSONAPIPaginationLinks |
|||
data |
X |
List of JSONAPICodeSystemResourceObject |
2.14. JSONAPIErrorObject
title : a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail : a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source : an object containing references to the primary source of the error.
status : the status code of error.
traceId : a unique identifier for this particular occurrence of the problem.
errorCode : an application-specific error code, expressed as a string value.
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
title |
String |
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. |
||
detail |
String |
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. |
||
source |
String |
An object containing references to the source of the error |
||
status |
String |
The HTTP status code applicable to this problem, expressed as a string value. |
||
traceId |
String |
A unique identifier for this particular occurrence of the problem. |
||
|
errorCode |
String |
An application-specific error code, expressed as a string value. |
2.15. JSONAPIErrorResponse
JSONAPIErrorResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
errors |
List of JSONAPIErrorObject |
2.16. JSONAPIMeta
**
Optional Metadata of this API. See JSON API Top Level Object.
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
|
api-version |
String |
The version of this API, adhering to the Semantic Versioning concept. |
||
version |
String |
The version of this Software Artifact, adhering to the Semantic Versioning concept. |
||
|
buildTimestamp |
String |
Software build timestamp. |
||
|
request-id |
String |
Identifier for this request. |
2.17. JSONAPIOrganizationResourceObject
"Resource objects” appear in a JSON:API document to represent resources.
A resource object MUST contain at least the following top-level members: * type * id
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
type |
X |
String |
||
id |
String |
|||
|
attributes |
Organization |
|||
links |
JSONAPISelfLinks |
2.18. JSONAPIOrganizationResponse
JSONAPIOrganizationResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
meta |
JSONAPIMeta |
|||
links |
JSONAPIPaginationLinks |
|||
data |
X |
|||
|
included |
2.19. JSONAPIPaginationLinks
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
self |
String |
Link to this page of results |
||
prev |
String |
Link to the previous page of results |
||
next |
String |
Link to the next page of results |
||
last |
String |
Link to the last page of results |
||
first |
String |
Link to the first page of results |
2.20. JSONAPIParentRelationshipObject
Parent organization
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
parent |
Parent |
2.21. JSONAPISelfLinks
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
self |
String |
Link to this page of results |
2.22. JSONAPISingleAddressResponse
JSONAPISingleAddressResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
meta |
JSONAPIMeta |
|||
links |
JSONAPIPaginationLinks |
|||
data |
X |
JSONAPIAddressResourceObject |
||
|
included |
2.23. JSONAPISingleCodeResponse
JSONAPISingleCodeResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
meta |
JSONAPIMeta |
|||
links |
JSONAPIPaginationLinks |
|||
data |
X |
JSONAPICodeResourceObject |
2.24. JSONAPISingleCodeSystemResponse
JSONAPISingleCodeSystemResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
meta |
JSONAPIMeta |
|||
links |
JSONAPIPaginationLinks |
|||
data |
X |
JSONAPICodeSystemResourceObject |
2.25. JSONAPISingleOrganizationResponse
JSONAPISingleOrganizationResponse
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
meta |
JSONAPIMeta |
|||
links |
JSONAPIPaginationLinks |
|||
data |
X |
JSONAPIOrganizationResourceObject |
||
|
included |
2.26. Organization
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
|
createdAt |
Date |
date-time |
||
|
updatedAt |
Date |
date-time |
||
name |
X |
String |
||
|
description |
X |
String |
||
|
alternateName |
String |
|||
|
participantIdentifier |
X |
String |
||
|
affiliation |
String |
|||
|
managementCode |
CodeWrapper |
|||
|
publicProvider |
Boolean |
|||
|
organizationNumber |
X |
String |
||
|
countryCode |
String |
Enum: SE, |
||
|
validCodeSystems |
List of CodeSystemWrapper |
|||
|
municipalityCode |
List of CodeWrapper |
|||
|
regionCode |
List of CodeWrapper |
|||
type |
String |
Enum: O, UO, |
||
|
participantStatus |
ParticipantStatus |
2.27. Parent
Parent
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
data |
ParentData |
2.28. ParentData
ParentData
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
String |
|||
type |
String |
Enum: organizations, addresses, codesystems, |
2.29. ParticipantStatus
ParticipantStatus
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
|
lastChecked |
String |
|||
result |
String |
Enum: OK, NOT_FOUND, |