wip: rest-api.yaml

evcc-io · Jan 1, 2025 · f0fd1e1 · f0fd1e1
1 parent fa71e7a
commit f0fd1e1
Showing 1 changed file with 209 additions and 30 deletions.
diff --git a/static/rest-api.yaml b/static/rest-api.yaml
@@ -1,8 +1,9 @@
+# Website used to generate these Tag-Comments: http://patorjk.com/software/taag/#f=Big
 openapi: "3.0.3"
 info:
-  title: evcc REST-API
-  description: "TODO: Alle möglichen Responses, Enums, Datentypregeln, Authentifizierung und Responseobjekte dokumentieren"
-  version: Latest
+  title: "evcc REST-API"
+  description: "TODO: Alle möglichen Responses, Enums, Datentypregeln, Authentifizierung, Configs (?) und Responseobjekte dokumentieren"
+  version: latest
 servers:
   - url: https://demo.evcc.io/api
 tags:
@@ -15,20 +16,14 @@ tags:
   - name: Vehicles
     description: TODO
 paths:
-  /state:
-    get:
-      summary: Get system state
-      description: TODO
-      tags:
-        - State
-      responses:
-        200:
-          description: TODO
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/State"
-  # -------------------
+  #   _______               _____ _ _
+  #  |__   __|         _   / ____(_) |
+  #     | | __ _  __ _(_) | (___  _| |_ ___
+  #     | |/ _` |/ _` |    \___ \| | __/ _ \
+  #     | | (_| | (_| |_   ____) | | ||  __/
+  #     |_|\__,_|\__, (_) |_____/|_|\__\___|
+  #               __/ |
+  #              |___/
   /health:
     get:
       summary: Health check
@@ -81,7 +76,7 @@ paths:
         - Site
       responses:
         200:
-          description: "TODO: Request does not work or does not respond?"
+          description: "TODO"
   /buffersoc/{soc}:
     post:
       summary: Set battery buffer soc
@@ -145,7 +140,7 @@ paths:
         - Site
       responses:
         200:
-          description: "TODO: Request does not work or does not respond?"
+          description: "TODO"
   /tariff/{type}:
     get:
       summary: Get list of tariff prices
@@ -180,13 +175,9 @@ paths:
                           type: object
                           properties:
                             start:
-                              description: TODO
-                              type: string
-                              format: date-time
+                              $ref: "#/components/schemas/Timestamp"
                             end:
-                              description: TODO
-                              type: string
-                              format: date-time
+                              $ref: "#/components/schemas/Timestamp"
                             price:
                               description: TODO
                               type: number
@@ -252,6 +243,139 @@ paths:
       responses:
         200:
           $ref: "#/components/responses/BooleanResult"
+  #   _______               _____ _        _
+  #  |__   __|         _   / ____| |      | |
+  #     | | __ _  __ _(_) | (___ | |_ __ _| |_ ___
+  #     | |/ _` |/ _` |    \___ \| __/ _` | __/ _ \
+  #     | | (_| | (_| |_   ____) | || (_| | ||  __/
+  #     |_|\__,_|\__, (_) |_____/ \__\__,_|\__\___|
+  #               __/ |
+  #              |___/
+  /state:
+    get:
+      summary: Get system state
+      description: TODO
+      tags:
+        - State
+      responses:
+        200:
+          description: TODO
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/State"
+  #   _______             __      __  _     _      _
+  #  |__   __|         _  \ \    / / | |   (_)    | |
+  #     | | __ _  __ _(_)  \ \  / /__| |__  _  ___| | ___  ___
+  #     | |/ _` |/ _` |     \ \/ / _ \ '_ \| |/ __| |/ _ \/ __|
+  #     | | (_| | (_| |_     \  /  __/ | | | | (__| |  __/\__ \
+  #     |_|\__,_|\__, (_)     \/ \___|_| |_|_|\___|_|\___||___/
+  #               __/ |
+  #              |___/
+  /vehicles/{name}/minsoc/{soc}:
+    post:
+      summary: Set minimum soc
+      description: TODO
+      tags:
+        - Vehicles
+      parameters:
+        - $ref: "#/components/parameters/vehicleName"
+        - $ref: "#/components/parameters/soc"
+      responses:
+        200:
+          description: TODO
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/responses/NumberResult"
+  /vehicles/{name}/limitsoc/{soc}:
+    post:
+      summary: Set soc-limit
+      description: TODO
+      tags:
+        - Vehicles
+      parameters:
+        - $ref: "#/components/parameters/vehicleName"
+        - $ref: "#/components/parameters/soc"
+      responses:
+        200:
+          description: TODO
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/responses/NumberResult"
+  /vehicles/{name}/plan/soc/{soc}/{timestamp}:
+    post:
+      summary: Set static plan
+      description: TODO
+      tags:
+        - Vehicles
+      parameters:
+        - $ref: "#/components/parameters/vehicleName"
+        - $ref: "#/components/parameters/soc"
+        - $ref: "#/components/parameters/timestamp"
+      responses:
+        200:
+          description: TODO
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StaticPlan"
+  /vehicles/{name}/plan/soc:
+    delete:
+      summary: Delete static plan
+      description: TODO
+      tags:
+        - Vehicles
+      parameters:
+        - $ref: "#/components/parameters/vehicleName"
+      responses:
+        200:
+          description: TODO
+  /vehicles/{name}/plan/repeating:
+    post:
+      summary: Set repeating plans
+      description: TODO
+      tags:
+        - Vehicles
+      parameters:
+        - $ref: "#/components/parameters/vehicleName"
+      requestBody:
+        description: TODO
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: "#/components/schemas/RepeatingPlan"
+      responses:
+        200:
+          description: TODO
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepeatingPlan"
+
+#   _______              _                     _             _       _
+#  |__   __|         _  | |                   | |           (_)     | |
+#     | | __ _  __ _(_) | |     ___   __ _  __| |_ __   ___  _ _ __ | |_ ___
+#     | |/ _` |/ _` |   | |    / _ \ / _` |/ _` | '_ \ / _ \| | '_ \| __/ __|
+#     | | (_| | (_| |_  | |___| (_) | (_| | (_| | |_) | (_) | | | | | |_\__ \
+#     |_|\__,_|\__, (_) |______\___/ \__,_|\__,_| .__/ \___/|_|_| |_|\__|___/
+#               __/ |                           | |
+#              |___/                            |_|
+
+#   _______               _____             __ _
+#  |__   __|         _   / ____|           / _(_)
+#     | | __ _  __ _(_) | |     ___  _ __ | |_ _  __ _
+#     | |/ _` |/ _` |   | |    / _ \| '_ \|  _| |/ _` |
+#     | | (_| | (_| |_  | |___| (_) | | | | | | | (_| |
+#     |_|\__,_|\__, (_)  \_____\___/|_| |_|_| |_|\__, |
+#               __/ |                             __/ |
+#              |___/                             |___/
 
 components:
   schemas:
@@ -261,6 +385,48 @@ components:
         result:
           description: TODO
           type: object
+    Soc:
+      description: Soc in %
+      type: number
+      minimum: 0
+      maximum: 100
+    Timestamp:
+      description: Timestamp
+      type: string
+      format: date-time
+    StaticPlan:
+      description: TODO
+      type: object
+      properties:
+        soc:
+          $ref: "#/components/schemas/Soc"
+        plan:
+          $ref: "#/components/schemas/Timestamp"
+    RepeatingPlan:
+      description: TODO
+      type: object
+      properties:
+        weekdays:
+          description: TODO
+          type: array
+          items:
+            description: TODO
+            type: integer
+            minimum: 0
+            maximum: 6
+        time:
+          description: TODO
+          type: string
+          pattern: "[0-1][0-9]:[0-5][0-9]"
+          format: "HH:MM"
+        tz:
+          description: Timezone in IANA format (TODO:Enum dafür?)
+          type: string
+        soc:
+          $ref: "#/components/schemas/Soc"
+        active:
+          description: TODO
+          type: boolean
   parameters:
     id:
       name: id
@@ -281,16 +447,29 @@ components:
           - type: string
           - type: number
         enum:
-          [1, 0, t, f, T, F, "true", "false", "TRUE", "FALSE", "True", "False"]
+          ["true", "false", 1, 0, t, f, T, F, "TRUE", "FALSE", "True", "False"]
     soc:
       name: soc
       in: path
-      description: Soc in %
       required: true
       schema:
-        type: number
-        minimum: 0
-        maximum: 100
+        $ref: "#/components/schemas/Soc"
+    timestamp:
+      name: timestamp
+      in: path
+      description: Timestamp
+      required: true
+      schema:
+        $ref: "#/components/schemas/Timestamp"
+    vehicleName:
+      name: name
+      in: path
+      description: Name of the vehicle
+      required: true
+      schema:
+        type: string
+        minLength: 1
+        pattern: "[a-zA-Z0-9_.:-]+"
     cost:
       name: cost
       in: path