blob: 4770d09e19ff12be0c574a89dd17a29d9dcb6767 [file] [log] [blame]
swagger: '2.0'
info:
title: Netzgebiete
description: Diese Schnittstelle ist Teil der [oK](http://www.openkonsequenz.de) Quellsystem-API.
version: Revision 3 (CIM 17v07)
contact:
name: BTC AG
url: http://www.btc-ag.com
email: openk@btc-ag.com
license:
name: Eclipse Public License 1.0
url: https://www.eclipse.org/legal/epl-v10.html
host: api.openk.de
schemes:
- http
basePath: /source-system/electricity/static-topology
produces:
- application/xml
paths:
/geographical-regions:
get:
summary: Die Schnittstelle gibt alle Netzgebiete der Topologie zurück. Die Netzgebiete dienen der Aufgliederung des elektrischen Netzes der gesamten Topologie.
parameters:
- name: revision
in: query
description: Version, die den Nachrichtenaustausch definiert. Dies ist nicht die CIM-Version.
required: true
type: integer
format: int32
minimum: 3
maximum: 3
- name: timestamp
in: query
description: Zeitpunkt, an dem die Nachricht versendet wurde (in UTC gemäß ISO-8601-Format YYYY-MM-DDTHH:mm:ss.SSSZ).
required: false
type: string
format: date-time
pattern: '^([0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|30|31)T(([0-1][0-9])|(2[0-3]))(:[0-5][0-9]){2}\.[0-9]{3}Z)$'
- name: source
in: query
description: Eindeutige Bezeichnung des Senders der Nachricht.
required: false
type: string
- name: user-id
in: query
description: Eindeutige Kennung des angemeldeten Nutzers (Sender).
required: false
type: string
- name: message-id
in: query
description: Eindeutige Kennung dieser Nachricht. Generiert vom Sender der Nachricht.
required: false
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: topology-id
in: query
description: Eindeutige Kennung der Topologie, für die der aktuelle Aufruf erfolgt. Wird der Parameter nicht angegeben, bezieht sich die Abfrage auf die aktuelle Topologie.
required: false
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
responses:
200:
description: Die CIM-Antwortnachricht.
schema:
$ref: '#/definitions/ResponseMessage'
400:
description: Die Schnittstelle wurde mit ungültigen Parametern aufgerufen.
410:
description: Die Topologie mit der angegebenen Kennung ist nicht mehr gültig.
500:
description: Es trat ein allgemeiner Fehler bei der Verarbeitung der Anfrage auf.
definitions:
### specific definitions ######################################################
GeographicalRegion:
description: Netzgebiet
type: object
properties:
mRID:
description: Die eindeutige Kennung des Netzgebietes.
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
name:
description: Der Name des Netzgebietes.
type: string
minLength: 1
maxLength: 64
description:
description: Die Beschreibung des Netzgebietes.
type: string
minLength: 1
maxLength: 2048
Names:
description: Referenzen auf alternative Namen.
type: array
minItems: 0
items:
$ref: '#/definitions/Name'
xml:
wrapped: true
Regions:
description: Referenz auf die Teilnetzgebiete.
type: array
minItems: 1
items:
$ref: '#/definitions/SubGeographicalRegion_Reference'
xml:
wrapped: true
required:
- mRID
xml:
name: GeographicalRegion
GeographicalRegions:
description: Auflistung der Netzgebiete
type: array
items:
$ref: '#/definitions/GeographicalRegion'
xml:
wrapped: true
Payload:
description: Der Inhalt der CIM-Antwortnachricht.
type: object
properties:
GeographicalRegions:
$ref: '#/definitions/GeographicalRegions'
required:
- GeographicalRegions
### common definitions ########################################################
Header_Reply:
description: Der Kopf der CIM-Nachricht.
type: object
properties:
Verb:
description: Hinweis, um welche Art von Nachricht es sich handelt.
type: string
default: reply
Noun:
description: Hinweis auf den Nachrichteninhalt.
type: string
Revision:
description: Version, die den Nachrichtenaustausch definiert. Dies ist nicht die CIM-Version.
type: integer
format: int32
minimum: 3
maximum: 3
Timestamp:
description: Zeitpunkt, an dem die Nachricht versendet wurde (in UTC gemäß ISO-8601-Format YYYY-MM-DDThh:mm:ss.sssZ).
type: string
format: date-time
pattern: '^([0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|30|31)T(([0-1][0-9])|(2[0-3]))(:[0-5][0-9]){2}\.[0-9]{3}Z)$'
Source:
description: Eindeutige Bezeichnung des Senders der Nachricht.
type: string
MessageID:
description: Eindeutige Kennung dieser Nachricht. Generiert vom Sender der Nachricht.
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
User:
$ref: '#/definitions/UserID'
required:
- Verb
- Noun
- Revision
- Timestamp
- Source
- MessageID
- User
xml:
name: Header
Name:
description: alternativer Name
type: object
properties:
name:
description: ein alternativer Name (z. B. Kennung aus dem Quellsystem)
type: string
minLength: 1
maxLength: 256
NameType:
$ref: '#/definitions/Name.NameType'
required:
- name
- NameType
xml:
name: Name
Name.NameType:
properties:
NameType:
$ref: '#/definitions/NameType'
xml:
name: NameType
NameType:
description: Namenstyp
type: object
properties:
name:
description: Name des Namestyps
type: string
minLength: 1
maxLength: 256
description:
description: Beschreibung des Namestyps
type: string
minLength: 1
maxLength: 2048
NameTypeAuthority:
$ref: '#/definitions/NameType.NameTypeAuthority'
required:
- name
- NameTypeAuthority
xml:
name: NameType
NameType.NameTypeAuthority:
properties:
NameTypeAuthority:
$ref: '#/definitions/NameTypeAuthority'
xml:
name: NameTypeAuthority
NameTypeAuthority:
description: Vergabestelle des Namestyps
type: object
properties:
name:
description: Name der Vergabestelle des Namestyps
type: string
minLength: 1
maxLength: 256
description:
description: Beschreibung des Namestyps
type: string
minLength: 1
maxLength: 2048
required:
- name
xml:
name: NameTypeAuthority
Reply_OK:
description: Die Antwort der CIM-Nachricht.
type: object
properties:
Result:
description: Antworttext
type: string
default: OK
required:
- Result
xml:
name: Reply
ResponseMessage:
description: Die CIM-Antwortnachricht.
type: object
properties:
Header:
$ref: '#/definitions/Header_Reply'
Reply:
$ref: '#/definitions/Reply_OK'
Payload:
$ref: '#/definitions/Payload'
required:
- Header
- Reply
- Payload
SubGeographicalRegion_Reference:
description: Referenz auf das Teilnetzgebiet
type: object
properties:
mRID:
description: eindeutige Kennung des Teilnetzgebietes
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
required:
- mRID
xml:
name: SubGeographicalRegion
UserID:
properties:
id:
description: Eindeutige Kennung des angemeldeten Nutzers (Empfänger).
type: string
xml:
name: UserID