blob: daaec118a52539bacc8a13a84506da4944e07647 [file] [log] [blame]
swagger: '2.0'
info:
title: Spannungsebenen
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:
/voltage-levels:
get:
summary: Die Schnittstelle gibt alle Spannungsebenen in den Stationen des Netzgebiets zurück. Stromnetze werden in Spannungsebenen eingeteilt, bei der sie elektrische Energie übertragen. Das Ergebnis dieses Schnittstellenaufrufs ist eine Auflistung der Spannungsebenen mit deren Beschreibungen, den dazugehörigen Referenzen auf das elektrische leitende Equipment, das zur Spannungsebene gehört sowie die jeweiligen eindeutigen Kennungen. Weiterhin werden die dazugehörigen Felder sowie die Referenzen auf die eindeutige Kennung der Stationen zurückgegeben.
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 ######################################################
Payload:
description: Der Inhalt der CIM-Antwortnachricht.
type: object
properties:
VoltageLevels:
$ref: '#/definitions/VoltageLevels'
required:
- VoltageLevels
VoltageLevel:
description: Spannungsebene
type: object
properties:
mRID:
description: Die eindeutige Kennung der Spannungsebene.
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 der Spannungsebene.
type: string
minLength: 1
maxLength: 64
description:
description: Die Beschreibung der Spannungsebene.
type: string
minLength: 1
maxLength: 2048
Names:
description: Referenzen auf alternative Namen.
type: array
minItems: 0
items:
$ref: '#/definitions/Name'
xml:
wrapped: true
Equipments:
description: Referenz auf das elektrische leitende Equipment, das zur Spannungsebene gehört.
type: array
items:
$ref: '#/definitions/Equipment_Reference'
xml:
wrapped: true
Bays:
description: Referenz auf die Felder, die zur Spannungsebene gehören.
type: array
items:
$ref: '#/definitions/Bay_Reference'
xml:
wrapped: true
BaseVoltage:
$ref: '#/definitions/VoltageLevel.BaseVoltage'
Substation:
$ref: '#/definitions/VoltageLevel.Substation'
required:
- mRID
- Equipments
xml:
name: VoltageLevel
VoltageLevel.BaseVoltage:
description: die Nennspannung
properties:
BaseVoltage:
$ref: '#/definitions/BaseVoltage_Reference'
required:
- BaseVoltage
xml:
name: BaseVoltage
VoltageLevel.Substation:
description: die Station
properties:
Substation:
$ref: '#/definitions/Substation_Reference'
required:
- Substation
xml:
name: Substation
VoltageLevels:
description: Auflistung der Spannungsebenen
type: array
items:
$ref: '#/definitions/VoltageLevel'
xml:
wrapped: true
### common definitions ########################################################
BaseVoltage_Reference:
description: Referenz auf die Nennspannung
type: object
properties:
mRID:
description: eindeutige Kennung der Nennspannung
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: BaseVoltage
Bay_Reference:
description: Referenz auf das Feld
type: object
properties:
mRID:
description: eindeutige Kennung des Feldes
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: Bay
Equipment_Reference:
description: Referenz auf elektrisch leitendes Equipment
type: object
properties:
mRID:
description: eindeutige Kennung des elektrisch leitenden Equipments
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: Equipment
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
Substation_Reference:
description: Referenz auf die Station
type: object
properties:
mRID:
description: eindeutige Kennung der Station
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: Substation
UserID:
properties:
id:
description: Eindeutige Kennung des angemeldeten Nutzers (Empfänger).
type: string
xml:
name: UserID