blob: 2450f37f54527c1818198009c7edf4ea249dbd54 [file] [log] [blame]
swagger: '2.0'
info:
title: Stationen
description: Diese Schnittstelle ist Teil der [oK](http://www.openkonsequenz.de) Quellsystem-API.
version: Revision 3 (CIM 07)
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:
/substations:
get:
summary: Die Schnittstelle gibt alle Stationen im Netzgebiet zurück. Stationen sind Teil des elektrischen Versorgungsnetzes und dienen der Verbindung unterschiedlicher Spannungsebenen. Das Ergebnis dieses Schnittstellenaufrufs ist eine Auflistung der Stationen mit den dazugehörigen Beschreibungen, den jeweiligen Stationstypen und den Referenzen auf das elektrische leitende Equipment, die Felder und die Spannungsebenen, die zur Station gehören sowie die jeweiligen eindeutigen Kennungen.
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:
Substations:
$ref: '#/definitions/Substations'
required:
- Substations
Substation:
description: Station
type: object
properties:
mRID:
description: Die 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}$'
name:
description: Der Name der Station.
type: string
minLength: 1
maxLength: 64
description:
description: Die Beschreibung der Station.
type: string
minLength: 1
maxLength: 2048
Names:
description: Referenzen auf alternative Namen.
type: array
minItems: 0
items:
$ref: '#/definitions/Name'
xml:
wrapped: true
PSRType:
$ref: '#/definitions/Substation.PSRType'
Equipments:
description: Referenz auf das elektrische leitende Equipment, das zur Station gehört.
type: array
minItems: 1
items:
$ref: '#/definitions/Equipment_Reference'
xml:
wrapped: true
VoltageLevels:
description: Referenz auf die Spannungsebenen, die zur Station gehören.
type: array
minItems: 0
items:
$ref: '#/definitions/VoltageLevel_Reference'
xml:
wrapped: true
Bays:
description: Referenz auf die Felder, die zur Station gehören.
type: array
minItems: 0
items:
$ref: '#/definitions/Bay_Reference'
xml:
wrapped: true
required:
- mRID
- Equipments
xml:
name: Substation
Substation.PSRType:
description: die Typ-Beschreibung
properties:
PSRType:
$ref: '#/definitions/PSRType_Reference'
required:
- PSRType
xml:
name: PSRType
Substations:
description: Auflistung der Stationen
type: array
items:
$ref: '#/definitions/Substation'
xml:
wrapped: true
### common definitions ########################################################
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
PSRType_Reference:
description: Referenz auf die Typ-Beschreibung
type: object
properties:
mRID:
description: eindeutige Kennung der Typ-Beschreibung
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: PSRType
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
UserID:
properties:
id:
description: Eindeutige Kennung des angemeldeten Nutzers (Empfänger).
type: string
xml:
name: UserID
VoltageLevel_Reference:
description: Referenz auf die Spannungsebene
type: object
properties:
mRID:
description: 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}$'
required:
- mRID
xml:
name: VoltageLevel