API version 1
Getting started
To get started, import V1 from the builtin api module.
from com_server import Connection, ConnectionRoutes, start_app
from com_server.api import V1
from flask import Flask
from flask_restful import Api
app = Flask(__name__)
api = Api(app)
conn = Connection(<baud>, "<serport>")
handler = ConnectionRoutes(conn)
# add your own routes and endpoints here
V1(handler)
start_app(app, api, handler)
V1 has an option prefix, indicating the prefix of all the routes in the builtin API. The default is v1, meaning that all version 1 API endpoints are prefixed with /v1/ (e.g. "send" below refers to "http://localhost:8080/v1/send").
Note that if you put V1 right before start_app and you have a resource that has the same path as one of the resources in the builtins, then the builtin resource will override your provided resource.
Notes and warnings
- Unlike the V0 API, the V1 API will respond with
200 OK, even with failures to send. The client should first check for the HTTP status code to see if their request was successful (i.e. serial port connected and not in use), but after that, they should check if "message" in the response is equal to "OK". - When disconnected, the receive queue of the serial connection will reset, meaning that the list from the /receive endpoint will be cleared.
- The V1 API is not compatable with the V0 API (cannot have routes from both APIs on the same server) because V0 uses the old
RestApiHandler, while V1 uses the newConnectionRoutesobject.
send
Sends data to the serial port.
HTTP method
POST
Parameters
| Parameter | Description | Data Type |
|---|---|---|
| data | Required. Data to send to the serial port. | integer |
| ending | Optional. Ending that will be appended to the end of the data before sending to the serial port. By default a carriage return. |
string |
| concatenate | Optional. What the strings in the data should be concatenated by if given in a list By default a space. |
string |
Response
| Response item | Description |
|---|---|
| message | Status of sending data. If OK, sending data was successful. Otherwise,the data failed to send. This would mainly be due to the send interval. |
| data | If message is OK, then data will be the data you sent. |
Error and status codes
The following table lists the status and error codes related to this request.
| Status code | Meaning |
|---|---|
| 200 | Successful response. |
| 400 | Bad request; parameters formatted incorrectly. |
| 500 | Serial port disconnected. |
| 503 | Serial port in use. |
receive/{num_before}
If num_before is ommitted, then returns the last queue_size received objects and the timestamps received in a list. If there are less than queue_size received objects, then it will just return a list of all received objects and the time they were received. Lastly, if there was nothing received at all since the server started, then it will return null for both lists.
num_before refers to how recent the received object should be. For example, if num_before is 0, then it will return the most recently received string. If num_before is 1, then it will return the second most recently received string. If there was nothing received num_before most recently, then it will respond with 404 Not Found.
HTTP method
GET
Parameters
No parameters
Response
The following table shows the responses if num_before is ommitted.
| Response item | Description |
|---|---|
| message | Status of receiving all data. Should be OK if serial port is connected. |
| data | If there was any data received from the serial port since the server started, then it should return a list of all received strings, with the size of the list up to queue_size. The most recently received string is the last element of the list. If there was no data at all received, this entire response will be null. |
| timestamps | If there was any data received from the serial port since the server started, then it should return a list of timestamps of all received data, with the size of the list up to queue_size. The timestamps are given in the UNIX timestamp format, represented with a float. The most recent timestamp is the last element of the list. If there was no data at all received, this entire response will be null. |
The following table shows the responses if num_before is there.
| Response item | Description |
|---|---|
| message | Status of receiving all data. Should be OK if serial port is connected. |
| data | The num_beforeth most recent received data from the serial port. For example,if num_before is 0, then data will be the most recently received string. If num_before is 1, then it will be the second most recently received string. This goes on until num_before is queue_size. If num_beforeth most recent received string is not found, then there will be a 404 Not Found response code. |
| timestamp | The UNIX timestamp that the data above was received by the serial port. |
Error and status codes
The following table lists the status and error codes related to this request.
| Status code | Meaning |
|---|---|
| 200 | Successful response. |
| 404 | If the receive item was not found. (only applies if num_before is there) |
| 500 | Serial port disconnected. |
| 503 | Serial port in use. |
get
Gets the first string received from the serial port after this endpoint is reached.
HTTP method
GET
Parameters
No parameters
Response
| Response item | Description |
|---|---|
| message | Status of getting data. OK if successful and Nothing received if nothing was received within timeout seconds. |
| data | If message is OK, then this represents the first string received from the serial port after the endpoint is reached. |
Error and status codes
The following table lists the status and error codes related to this request.
| Status code | Meaning |
|---|---|
| 200 | Successful response. |
| 500 | Serial port disconnected. |
| 503 | Serial port in use. |
first_response
Gets the first response from the serial port after sending some data.
HTTP method
POST
Parameters
| Parameter | Description | Data Type |
|---|---|---|
| data | Required. Data to send to the serial port. | integer |
| ending | Optional. Ending that will be appended to the end of the data before sending to the serial port. By default a carriage return. |
string |
| concatenate | Optional. What the strings in the data should be concatenated by if given in a list By default a space. |
string |
Response
| Response item | Description |
|---|---|
| message | Status of getting data. OK if successful and Nothing received if nothing was received within timeout seconds. |
| data | If message is OK, then this represents the first string received from the serial port after the data above was sent to the serial port. |
Error and status codes
The following table lists the status and error codes related to this request.
| Status code | Meaning |
|---|---|
| 200 | Successful response. |
| 400 | Bad request; parameters formatted incorrectly. |
| 500 | Serial port disconnected. |
| 503 | Serial port in use. |
send_until
Sends data until a certain string is received from the serial port.
HTTP method
POST
Parameters
| Parameter | Description | Data Type |
|---|---|---|
| response | Required. The receive data that the program will look for while sending. | string |
| data | Required. Data to send to the serial port. | integer |
| ending | Optional. Ending that will be appended to the end of the data before sending to the serial port. By default a carriage return. |
string |
| concatenate | Optional. What the strings in the data should be concatenated by if given in a list By default a space. |
string |
Response
| Response item | Description |
|---|---|
| message | Status of getting data. OK if successful and Nothing received if the response above was received within timeout seconds. |
| data | If message is OK, then this represents the data you sent as a request. |
Error and status codes
The following table lists the status and error codes related to this request.
| Status code | Meaning |
|---|---|
| 200 | Successful response. |
| 400 | Bad request; parameters formatted incorrectly. |
| 500 | Serial port disconnected. |
| 503 | Serial port in use. |
connection_state
Returns the properties of the connection object.
HTTP method
GET
Parameters
No parameters
Response
| Response item | Description |
|---|---|
| message | Status of getting connection state. Should be OK if serial port is connected. |
| state | An object containing properties of the connection. |
Here are the properties found in state:
| Property | Description |
|---|---|
| connected | A boolean representing if the serial port is connected or not. |
| timeout | An integer representing the timeout of the Connection object. |
| send_interval | An integer representing the send interval of the Connection object. |
| available | An integer representing how many new serial port items are available since the last time you received an item. |
| port | A string representing the serial port of the connection. |
Error and status codes
The following table lists the status and error codes related to this request.
| Status code | Meaning |
|---|---|
| 200 | Successful response. |
| 500 | Serial port disconnected. |
| 503 | Serial port in use. |
all_ports
Returns the properties of the connection object.
HTTP method
GET
Parameters
No parameters
Response
| Response item | Description |
|---|---|
| message | Status of getting connection state. Should be OK if serial port is connected. |
| ports | A list of lists of size 3, where each list represents info for a port, and each sublist contains the port, description, and technical description of that port. |
Error and status codes
The following table lists the status and error codes related to this request.
| Status code | Meaning |
|---|---|
| 200 | Successful response. |
| 500 | Serial port disconnected. |
| 503 | Serial port in use. |