blob: 2aa0c229892b7becf59a125b22e1c39c844532ac [file] [log] [blame]
swagger: '2.0'
info:
title: Petersenspulen
description: Diese Schnittstelle ist Teil der [oK](http://www.openkonsequenz.de) Quellsystem-API.
version: Revision 1 (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:
/petersen-coils:
get:
summary: Die Schnittstelle gibt alle möglichen Petersenspulen im Netzgebiet zurück. Das Ergebnis dieses Schnittstellenaufrufs ist eine Auflistung der Petersenspulen mit ihren dazugehörigen eindeutigen Kennungen, Beschreibungen und Terminals sowie der Referenz auf die eindeutige Kennnung der Nennspannung. Weiterhin werden Informationen zum Stromfluss und zum Spektrum des Blindwiderstands der Petersenspulen 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: 1
maximum: 1
- 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 ######################################################
PetersenCoil:
description: Petersenspule
type: object
properties:
mRID:
description: Die eindeutige Kennung der Petersenspule.
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 Petersenspule.
type: string
minLength: 1
maxLength: 64
description:
description: Die Beschreibung der Petersenspule.
type: string
minLength: 1
maxLength: 2048
Names:
description: Referenzen auf alternative Namen.
type: array
minItems: 0
items:
$ref: '#/definitions/Name'
xml:
wrapped: true
mode:
description: Operationsmodus für Petersenspulen
type: string
enum:
- fixed
- manuel
- automaticPositioning
offsetCurrent:
$ref: '#/definitions/CurrentFlow'
positionCurrent:
$ref: '#/definitions/CurrentFlow'
xGroundMax:
$ref: '#/definitions/Reactance'
xGroundMin:
$ref: '#/definitions/Reactance'
xGroundNominal:
$ref: '#/definitions/Reactance'
BaseVoltage:
$ref: '#/definitions/PetersenCoil.BaseVoltage'
Terminals:
description: Terminals.
type: array
minItems: 1
maxItems: 1
items:
$ref: '#/definitions/Terminal'
xml:
wrapped: true
required:
- mRID
- mode
- Terminals
xml:
name: PetersenCoil
PetersenCoil.BaseVoltage:
description: die Nennspannung
properties:
BaseVoltage:
$ref: '#/definitions/BaseVoltage_Reference'
required:
- BaseVoltage
xml:
name: BaseVoltage
PetersenCoils:
description: Auflistung der Petersenspulen
type: array
items:
$ref: '#/definitions/PetersenCoil'
xml:
wrapped: true
Payload:
description: Der Inhalt der CIM-Antwortnachricht.
type: object
properties:
PetersenCoils:
$ref: '#/definitions/PetersenCoils'
required:
- PetersenCoils
### 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
ConnectivityNode:
description: Verknüpfungspunkt.
type: object
properties:
mRID:
description: eindeutige Kennung des Verknüpfungspunkts
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: Name des Verknüpfungspunkts
type: string
minLength: 1
maxLength: 64
required:
- mRID
xml:
name: ConnectivityNode
CurrentFlow:
description: Stromfluss
type: object
properties:
multiplier:
description: Multiplikator des Stromflusses (CIM UnitMultiplier).
type: string
default: none
enum:
- a
- c
- d
- da
- E
- f
- G
- h
- k
- m
- M
- micro
- n
- none
- p
- P
- T
- y
- Y
- z
- Z
unit:
description: Einheit des Stromflusses (CIM UnitSymbol).
type: string
default: A
enum:
- A
value:
description: Wert des Stromflusses
type: number
format: float
minimum: 0
required:
- multiplier
- unit
- value
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: 1
maximum: 1
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
Reactance:
description: Blindwiderstand
type: object
properties:
multiplier:
description: Multiplikator des Blindwiderstands (CIM UnitMultiplier).
type: string
default: none
enum:
- a
- c
- d
- da
- E
- f
- G
- h
- k
- m
- M
- micro
- n
- none
- p
- P
- T
- y
- Y
- z
- Z
unit:
description: Einheit des Blindwiderstands (CIM UnitSymbol).
type: string
default: ohm
enum:
- ohm
value:
description: Wert des Blindwiderstands
type: number
format: float
minimum: 0
required:
- multiplier
- unit
- value
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
Terminal:
description: Terminal
type: object
properties:
mRID:
description: eindeutige Kennung des Terminals
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: Name des Terminals
type: string
minLength: 1
maxLength: 64
ConnectivityNode:
$ref: '#/definitions/Terminal.ConnectivityNode'
required:
- mRID
- ConnectivityNode
xml:
name: Terminal
Terminal.ConnectivityNode:
description: Verknüpfungspunkt
type: object
properties:
ConnectivityNode:
$ref: '#/definitions/ConnectivityNode'
required:
- ConnectivityNode
xml:
name: ConnectivityNode
UserID:
properties:
id:
description: Eindeutige Kennung des angemeldeten Nutzers (Empfänger).
type: string
xml:
name: UserID