Merge pull request #34 from unfoldedcircle/migrate/api-doc

Migrate Core-API specification from core-simulator

.github/workflows/asyncapi.yml

@@ -4,14 +4,14 @@ on:
   push:
     paths:
       - 'dock-api/**'
-      - 'websocket-api/**'
+      - 'core-api/websocket/**'
       - 'integration-api/**'
       - '.github/workflows/asyncapi.yml'
   pull_request:
     types: [ opened, synchronize, reopened ]
     paths:
       - 'dock-api/**'
-      - 'websocket-api/**'
+      - 'core-api/websocket/**'
       - 'integration-api/**'
       - '.github/workflows/asyncapi.yml'
 
@@ -21,20 +21,20 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
-#      - name: Validate websocket-api
-#        uses: WaleedAshraf/asyncapi-github-action@v0.0.9
-#        with:
-#          filepath: './websocket-api/asyncapi.yaml'
+      - name: Validate websocket-api
+        uses: WaleedAshraf/asyncapi-github-action@v0.0.10
+        with:
+          filepath: './core-api/websocket/UCR2-asyncapi.yaml'
 
       - name: Validate integration-api
-        uses: WaleedAshraf/asyncapi-github-action@v0.0.9
+        uses: WaleedAshraf/asyncapi-github-action@v0.0.10
         with:
           filepath: './integration-api/asyncapi.yaml'
 
       - name: Validate dock-api
-        uses: WaleedAshraf/asyncapi-github-action@v0.0.9
+        uses: WaleedAshraf/asyncapi-github-action@v0.0.10
         with:
           filepath: './dock-api/UCD2-asyncapi.yaml'
 
@@ -51,6 +51,10 @@ jobs:
           fi;
           ag --version
 
+      - name: Generate core AsyncAPI HTML doc
+        run: |
+          ag ./core-api/websocket/UCR2-asyncapi.yaml @asyncapi/html-template -o ./static/api/ws --force-write
+
       - name: Generate integration AsyncAPI HTML doc
         run: |
           ag ./integration-api/asyncapi.yaml @asyncapi/html-template -o ./static/api/integration --force-write
@@ -59,15 +63,22 @@ jobs:
         run: |
           ag ./dock-api/UCD2-asyncapi.yaml @asyncapi/html-template -o ./static/api/dock --force-write
 
+      - name: Deploy core API GH page
+        uses: JamesIves/github-pages-deploy-action@v4.5.0
+        with:
+          branch: gh-pages
+          folder: ./static/api/ws
+          target-folder: ./ws
+
       - name: Deploy integration API GH page
-        uses: JamesIves/github-pages-deploy-action@v4.3.0
+        uses: JamesIves/github-pages-deploy-action@v4.5.0
         with:
           branch: gh-pages
           folder: ./static/api/integration
           target-folder: ./integration
 
       - name: Deploy dock API GH page
-        uses: JamesIves/github-pages-deploy-action@v4.3.0
+        uses: JamesIves/github-pages-deploy-action@v4.5.0
         with:
           branch: gh-pages
           folder: ./static/api/dock

.github/workflows/openapi.yml

@@ -3,23 +3,23 @@ name: OpenAPI
 on:
   push:
     paths:
-      - 'rest-api/**'
-#      - '.github/workflows/openapi.yml'
+      - 'core-api/rest/**'
+      - '.github/workflows/openapi.yml'
   pull_request:
     types: [ opened, synchronize, reopened ]
     paths:
-      - 'rest-api/**'
-#      - '.github/workflows/openapi.yml'
+      - 'core-api/rest/**'
+      - '.github/workflows/openapi.yml'
 
 jobs:
   validate:
     name: Validate OpenAPI
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Validate
         uses: mbowman100/swagger-validator-action@master
         with:
           files: |
-            ./rest-api/openapi.yaml
+            ./core-api/rest/UCR2-openapi.yaml

CHANGELOG.md

@@ -11,6 +11,7 @@ _Changes in the next release_
 ### Changed
 - Rename media-player `select_sound_mode` command parameter from `sound_mode` to `mode`.
 - Integration API: add `reconfigure` flag in `setup_driver` request message to reconfigure a driver.
+- Migrated REST- & WebSocket Core-APIs from the core-simulator repository to the `core-api` directory. 
 
 ---
 

README.md

@@ -1,4 +1,5 @@
-[![AsyncAPI Validation](https://github.com/unfoldedcircle/core-api/actions/workflows/asyncapi.yml/badge.svg)](https://github.com/unfoldedcircle/core-api/actions/workflows/asyncapi.yml)
+[![AsyncAPI Validation](https://github.com/unfoldedcircle/core-api/actions/workflows/asyncapi.yml/badge.svg)](https://github.com/unfoldedcircle/core-api/actions/workflows/asyncapi.yml) 
+[![OpenAPI Validation](https://github.com/unfoldedcircle/core-api/actions/workflows/openapi.yml/badge.svg)](https://github.com/unfoldedcircle/core-api/actions/workflows/asyncapi.yml)
 
 # Unfolded Circle Core APIs
 
@@ -11,12 +12,10 @@ This repository contains API specifications of [Unfolded Circle Remote Two](http
 API definitions:
 
 - [WebSocket Integration API](./integration-api/README.md) defined with [AsyncAPI](https://www.asyncapi.com/).
-- [WebSocket Core API](https://github.com/unfoldedcircle/core-simulator/tree/main/core-api) defined with [AsyncAPI](https://www.asyncapi.com/)
-- [REST Core API](https://github.com/unfoldedcircle/core-simulator/tree/main/core-api) defined with [OpenAPI](https://www.openapis.org/)
+- [WebSocket Core API](./core-api/websocket/README.md) defined with [AsyncAPI](https://www.asyncapi.com/)
+- [REST Core API](./core-api/rest/README.md) defined with [OpenAPI](https://www.openapis.org/)
 - [WebSocket Dock API](./dock-api/README.md) defined with [AsyncAPI](https://www.asyncapi.com/)
 
-ℹ️  The Core-APIs will be migrated to this repository soon.
-
 Integration driver documentation:
 
 - [Remote Two entities](doc/entities/README.md).
@@ -68,16 +67,9 @@ We plan to release more examples in the future.
 ## Core APIs
 
 The Remote Two WebSockets & REST core APIs allow you to interact with the Unfolded Circle remote-core application and
-take full control of its features. The APIs are specialized for certain features, but otherwise contain the same
-functionality.
-
-- The REST API adds:
-  - custom resource handling for uploading icons, images etc.
-  - user management and authentication handling.
-- The WebSockets API adds event subscription with asynchronous notifications. 
+take full control of its features.
 
-The Remote Two acts as server. Whenever the remote enters standby it may choose to disconnect open WebSocket sessions.
-It is up to the client to reconnect again.
+See [core-api](./core-api) directory for more information.
 
 ## Other resources
 

core-api/README.md

@@ -0,0 +1,17 @@
+# Remote Two Core-APIs
+
+The Remote Two WebSockets & REST Core-APIs allow you to interact with the Unfolded Circle remote-core application and
+take full control of its features. The APIs are specialized for certain tasks, but otherwise contain the same
+functionality.
+
+- The REST API adds:
+    - Custom resource handling for uploading icons, images etc.
+    - User management and authentication handling.
+- The WebSockets API adds:
+    - Event subscription with asynchronous notifications.
+
+The API specifications are defined with [OpenAPI](https://swagger.io/specification/) & [AsyncAPI](https://www.asyncapi.com/)
+in YAML format.
+
+- [REST Core-API](rest)
+- [WebSocket Core-API](websocket)

core-api/rest/README.md

@@ -0,0 +1,29 @@
+# Remote Two REST Core-API
+
+The Core-API is defined with [OpenAPI](https://www.openapis.org/).
+
+You can use the online [Swagger Editor](https://editor.swagger.io/) to load and browse the specification or use your
+favorite IDE with OpenAPI support (e.g. IntelliJ or Visual Studio Code).
+
+- [OpenAPI YAML definition](UCR2-openapi.yaml).
+  - ℹ️ This is a bundled YAML file generated from individual definitions.
+  - Most OpenAPI tools only work with a single file.
+  - We might publish the original definitions at a later time.
+- See [/doc folder](../../doc/README.md) for further API documentation and information.
+
+## Postman Collection
+
+For explorative API testing the `remote-core_rest-api.postman_collection.json` collection can be imported into
+[Postman](https://www.postman.com/). It contains pre-defined requests and some helper scripts to propagate generated
+identifier keys to simplify common tasks.
+
+Postman also supports [importing OpenAPI definitions](https://learning.postman.com/docs/integrations/available-integrations/working-with-openAPI/).  
+
+### Configuration
+
+The admin user account password needs to be configured in the Postman collection:
+
+1. Open the `Remote Two Core-API` collection
+2. Select the `Variables` tab.
+3. Set the `apiPassword` and `apiKeyId` in the **CURRENT VALUE** column.  
+   This will keep the passwords local and won't save them in the collection or Postman cloud.