

Base Station REST API

Before digging into the API, it's useful to list all the use-cases it needs to cover.

Each use cases will be supported by one or more methods in the webserver, exposed as a REST API.

Functional Requirements

1. Identify base station, including firmware version, serial number and nickname
2. Update base station nickname
3. List files on base station SD Card, including filenames, size, and mime type
4. Upload files on the base station SD Card (filter invalid uploads from the app)
5. List tags recognized by base station
6. Start scanning for a new tag
7. Update the bindings between files and tags
8. Download bindings between files and tags
9. Update firmware

Technical requirements

HTTP

The communication should happen over HTTP/HTTPs using the default port 80 / 443.

The clients will discover a base station using the created AdHoc Wifi Network.

JSON-API Standard

The API is designed according the JSON-API standard to improve reuse and interoperability. See JSON API Cheatsheet

Security

The base station will never connect to a public wifi network, so security is a limited concern.

NOTE: this only applies to the current implmentation and should be revised if new solutions are adopted.

API Specification

Models

Station information

Attribute	Type	Description
fw_version	string	the firmware version number in xx.xx.xx format
hw_version	string	the hardware version number in xx.xx.xx format (reserved for future use)
serial	string	serial number for this base station, genereated from wifi mac address
nickname	string	the base station nickname

Settings

Attribute	Type	Description
value	string	the value for this setting

File

Attribute	Type	Description
filename	string	the filename, including extension
size	integer	the file size in bytes

Tag

Attribute	Type	Description
model	string	the tag model, either 'mifare' or 'mifare_classic'
serial	string	the hex representation for a tag
filename	string	the filename associated to this tag

SDCard Info

Attribute	Type	Description
size	integer	the tag model, either 'mifare' or 'mifare_classic'
available	integer	the hex representation for a tag
files	[File]	the files contained in this card

REST API

Get version information

GET /api/v1/settings

Response

{
  "data": {
    "fw_version": "1.0.0",
    "hw_version": "1.0.0",
    "serial": "0x00aabbcc",
    "nickname": "Micromuseum XX"
  }
}

Update settings

Only works with read-write settings, currently only nickname.

To update nickname:

PATCH /api/v1/settings

{
  "data": {
    "type": "setting",
    "id": "1",
    "attributes": {
      "nickname": "To TDD or Not"
    }
  }
}

Response

200 OK

List SD Card contents

Request

GET /api/v1/sdcard

Response

200 OK

{
  "links": {
    "self": "/api/v1/sdcard"
  },
  "data": {
    "id": "sdcard",
    "type": "sdcard",
    "size": "12343423",
    "free": "13342344",
    "files": [{ "id": 1, "type": "file" }, { "id": 2, "type": "file" }]
  },
  "included": [
    {
      "id": 1,
      "type": "file",
      "attributes": {
        "filename": "track001.mp3",
        "size": 1234324234
      }
    },
    {
      "id": 1,
      "type": "file",
      "attributes": {
        "filename": "track001.mp3",
        "size": 1234324234
      }
    }
  ]
}

Upload file to SD Card

Request

POST /api/v1/files

{
  "data": {
    "type": "file",
    "filename": "track001.mp3",
    "media_type": "audio/x-mp3",
    "encoding": "base64",
    "encoded": "<content encoded according to encoding, default base64>"
  }
}

Response

201 Created

Delete file from SD Card

DELETE /api/v1/files/1

List tags

Request

GET /api/v1/tags

Response

200 OK

{
  "links": {
    "self": "/api/v1/tags"
  },
  "data": [{ "id": 1, "type": "tag" }],
  "included": [{ "id": 1, "type": "tag", "attributes": {
      "model": "mifare", "serial": "0x00000000", "filename": null}

  } }]
}

Update tag

Request

PATCH /api/v1/tags/1

{
  "data": {
    "id": "1",
    "type": "tag",
    "attributes": {
      "filename": "track0001.mp3"
    }
  }
}

Response

200 OK

Discover new tags

Request

GET /api/v1/scanner/tags

Parameters:

name	description
timeout	seconds to wait before returning an empty result

Response

200 OK

{
  "data": [{ "id": 1, "type": "tag" }],
  "included": [
    {
      "id": 1,
      "type": "tag",
      "model": "mifare",
      "serial": "0x00000000",
      "filename": null
    }
  ]
}

Update firmware

Request

PATCH /api/v1/firmware

Parameters

name	description
update	multipart/form-data encoded firmware file

Response

200 OK

In case of errors, an error object is returned:

{
  "errors": [
    {
      "type": "error",
      "id": 500,
      "title": "Unable to update firmware",
      "status": 500
    }
  ]
}