feat: add REST API description

.github/workflows/api.yml

@@ -0,0 +1,22 @@
+name: API checks
+
+on:
+  push:
+    paths:
+    - 'docs/api/**'
+  pull_request:
+    paths:
+    - 'docs/api/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install OpenAPI spec validator
+      run: pip install openapi-spec-validator
+
+    - name: Check RATSD API
+      run: make -C docs/api check

docs/api/Makefile

@@ -0,0 +1,31 @@
+.DEFAULT_GOAL := help
+
+# To validate an OpenAPI module, append the file name (without the .yaml
+# extension) to the API variable.  A "check_<YAML module>" target is
+# automatically constructed and appended to the top level "check" goal.
+API := ratsd
+
+CMD := openapi-spec-validator
+
+ifeq (, $(shell which $(CMD)))
+$(error "No openapi-spec-validator in $(PATH); To install it, run: 'pip install openapi-spec-validator'")
+endif
+
+define OPENAPI_CHECK_template
+.PHONY: check_$(1)
+
+check_$(1): ; @printf ">>> $(1): " && $(CMD) $(1).yaml
+
+HELP += "check_$(1): check only the $(1) template"
+endef
+
+$(foreach a,$(API),$(eval $(call OPENAPI_CHECK_template,$(a))))
+
+.PHONY: check
+check: $(foreach t,$(API),check_$(t))
+
+.PHONY: help
+help:
+	@printf "\nAvailable targets:\n"
+	@printf "\tcheck: run the OpenAPI spec validator on all API templates\n\n"
+	@printf "\t%s\n\n" $(HELP)

docs/api/ratsd.yaml

@@ -0,0 +1,149 @@
+openapi: 3.0.0
+info:
+  title: RATS Evidence Collection Daemon API
+  version: 0.0.1
+tags: []
+paths:
+  /ratsd/chares:
+    post:
+      description: Challenge response API. Accepts a challenge and, upon success, generates the evidence in EAT w/ CMW format.
+      operationId: Ratsd_chares
+      parameters:
+        - $ref: '#/components/parameters/ChaResRequestParameters.accept'
+      responses:
+        '200':
+          description: The request has succeeded.
+          content:
+            application/eat+jwt; eat_profile="tag:github.com,2024:veraison/ratsd":
+              schema:
+                $ref: '#/components/schemas/EAT'
+        '400':
+          description: The server could not understand the request due to invalid syntax.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/BadRequestError'
+        '401':
+          description: Access is unauthorized.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/UnauthorizedError'
+      requestBody:
+        required: true
+        content:
+          application/vnd.veraison.chares+json:
+            schema:
+              $ref: '#/components/schemas/ChaResRequest'
+      security:
+        - BearerAuth: []
+components:
+  parameters:
+    ChaResRequestParameters.accept:
+      name: accept
+      in: header
+      required: false
+      schema:
+        type: string
+  schemas:
+    BadRequestError:
+      type: object
+      required:
+        - type
+        - title
+        - status
+      properties:
+        type:
+          type: string
+          enum:
+            - tag:github.com,2024:veraison/ratsd:error:invalidrequest
+        title:
+          type: string
+          enum:
+            - invalid request
+        status:
+          type: number
+          enum:
+            - 400
+        detail:
+          type: string
+        instance:
+          type: string
+    CMW:
+      type: object
+      required:
+        - typ
+        - val
+      properties:
+        typ:
+          type: string
+          enum:
+            - application/vnd.veraison.configfs-tsm+json
+        val:
+          type: string
+          format: base64url
+    ChaResRequest:
+      type: object
+      required:
+        - nonce
+      properties:
+        nonce:
+          type: string
+          format: base64url
+    EAT:
+      type: object
+      required:
+        - eat_profile
+        - nested-token
+      properties:
+        eat_profile:
+          type: string
+          enum:
+            - tag:github.com,2024:veraison/ratsd
+        nested-token:
+          $ref: '#/components/schemas/CMW'
+    ProblemDetails:
+      type: object
+      properties:
+        type:
+          type: string
+        title:
+          type: string
+        status:
+          type: integer
+        detail:
+          type: string
+        instance:
+          type: string
+    UnauthorizedError:
+      type: object
+      required:
+        - type
+        - title
+        - status
+      properties:
+        type:
+          type: string
+          enum:
+            - tag:github.com,2024:veraison/ratsd:error:unauthorized
+        title:
+          type: string
+          enum:
+            - access unauthorized
+        status:
+          type: number
+          enum:
+            - 401
+        detail:
+          type: string
+        instance:
+          type: string
+    Versions:
+      type: string
+      enum:
+        - 0.0.1
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+