Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add OpenAPI definition and update readme #27

Merged
merged 1 commit into from
Feb 12, 2024
Merged

Add OpenAPI definition and update readme #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 5 additions & 79 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,82 +75,8 @@ This project welcomes contributions. Please follow the regular git workflow; for

### Backend
- C++ based API with mDns, a web server, local file system, and a bunch of other things.
#### API Specification

<details>

<summary>The API has 4 endpoints. Expand to see more.</summary>

### `status`
```
GET http://winderoo.local/api/status
```
- Provides the current state of Winderoo

#### Response Code 200
- Response Body
```json
{
"status": "Stopped",
"rotationsPerDay": "300",
"direction": "BOTH",
"hour": "12",
"minutes": "50",
"durationInSecondsToCompleteOneRevolution": 8,
"startTimeEpoch": 0,
"currentTimeEpoch": 1680555863,
"estimatedRoutineFinishEpoch": 0,
"winderEnabled": "1",
"timerEnabled": "1",
"db": -67
}
```

### `power`
```
POST http://winderoo.local/api/power
```
- Toggles the winder enable/disable state of Winderoo.

#### Response Code 204
- *No Response Body*

### `update`
```
POST http://winderoo.local/api/update
```
- Updates the state of Winderoo and writes settings to NVRAM
- Accepts the following Request Params:
```
tpd= number
hour= number
minutes= number
timerEnabled= number
action= START | STOP
rotationDirection= CW | CCW | BOTH
```

Example Request:
- [`http://winderoo.local/api/update?action=STOP&rotationDirection=BOTH&tpd=300&hour=12&minutes=50`](http://winderoo.local/api/update?action=STOP&rotationDirection=BOTH&tpd=300&hour=12&minutes=50)


#### Response Code 204
- *No Response Body*

### `reset`

```
GET http://winderoo.local/api/reset
```
- Triggers Winderoo'a reset countdown.
- WiFi credentials are reset and cleared from NVRAM; Winderoo enters setup mode.

#### Response Code 200
- Response Body
```json
{
"status": "Resetting"
}
```

</details>

### API Specification

The API has 4 endpoints. You can explore them in the attached Open API definition.
- [Open API Definition](./openapi.yml)
152 changes: 152 additions & 0 deletions openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
openapi: 3.1.0
info:
title: Winderoo API
version: 0.1.0
servers:
- url: http://winderoo.local/api/
description: local development and deployed devices
tags:
- name: Status
description: Retrieve the current state of Winderoo
- name: Modify
description: Modify the state of Winderoo
paths:
/update:
post:
tags:
- Modify
description: Change the state of Winderoo
parameters:
- in: query
name: tpd
schema:
type: integer
description: how many turns are required
example: 330
- in: query
name: hour
schema:
type: integer
description: At what hour winderoo should begin winding at
example: 14
- in: query
name: minutes
schema:
type: integer
description: At what minute winderoo should begin winding at
example: 50
- in: query
name: timerEnabled
schema:
type: integer
description: Whether Winderoo should enable alarm-start winding; number represents a boolean where 0 == off and 1 == on
example: 0, 1
- in: query
name: action
schema:
type: string
description: Whether Winderoo should start or stop winding
example: START, STOP
- in: query
name: rotationDirection
schema:
type: string
description: The winding direction
example: CW, CCW, BOTH
responses:
'204':
description: Successful opeation
'500':
description: Something went wrong when writing to memory
/status:
get:
tags:
- Status
description: Get the current status of Winderoo
responses:
'200':
description: Service is alive with current winder state
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/power:
post:
tags:
- Modify
description: Toggle whether Winderoo is on or off (hard off state)
responses:
'204':
description: State toggled succesfully
/reset:
get:
tags:
- Modify
description: Resets Winderoo's network settings; re-initializes winderoo with setup access point
responses:
'200':
description: State toggled succesfully
content:
application/json:
schema:
$ref: '#/components/schemas/Resetting'
components:
schemas:
Status:
type: object
properties:
status:
type: string
examples:
- Stopped
rotationsPerDay:
type: string
examples:
- 300
direction:
type: string
examples:
- BOTH
hour:
type: string
examples:
- 12
minutes:
type: string
examples:
- 50
durationInSecondsToCompleteOneRevolution:
type: number
examples:
- 8
startTimeEpoch:
type: number
examples:
- 0
currentTimeEpoch:
type: number
examples:
- 1680555863
estimatedRoutineFinishEpoch:
type: number
examples:
- 0
winderEnabled:
type: string
examples:
- 1
timerEnabled:
type: string
examples:
- 1
db:
type: number
examples:
- -67
Resetting:
type: object
properties:
status:
type: string
examples:
- Resetting
Loading