Skip to content

Web API (Badger State)

Jump to bottom
Jason Bertsche edited this page Jun 27, 2019 · 6 revisions

All API methods expect to receive the parameters as content type application/x-www-form-urlencoded.

/badgerstate/join/{{group-id}}

  • Method: POST
  • Parameters:
    • group-id: The identifier that is being used for the class/group that subsequent data should be connected with
  • Response Type: text/plain
  • Description: Generates a unique identifier for the requester that will be used for sending/receiving subsequent data. Ensures that the unique identifier will be available in the response from /badgerstate/participants. Responds with the unique identifier.
  • Error Conditions:
    • group-id is missing or empty (HTTP 422)

/badgerstate/participants/{{group-id}}

  • Method: GET
  • Parameters:
    • group-id: The identifier of the class/group in question
  • Response Type: application/json
  • Description: Responds with a JSON array of strings of unique identifiers of members of the group (as generated by /badgerstate/join), where the array is ordered by join time, such that the first identifier is the most recent joiner and the last identifier is the least recent joiner.
  • Error Conditions:
    • group-id is missing or empty (HTTP 422)

/badgerstate/data/{{group-id}}/{{bucket-id}}/{{data}}

  • Method: POST
  • Parameters:
    • group-id: The identifier of the class/group associated with the bucket
    • bucket-id: The identifier (UUID) of the bucket itself, as returned by /badgerstate/join
    • data: The arbitrary data to be stored
  • Response Type: text/plain
  • Description: Stores the data on the server for future retrieval. Responds with the POSIX timestamp (in microseconds) for when the data was added to the database.
  • Error Conditions:
    • group-id is missing or empty (HTTP 422)
    • bucket-id is missing or an invalid UUID (HTTP 422)
    • data is missing or empty (HTTP 422)

/badgerstate/data/{{group-id}}/{{bucket-id}}/{{timestamp}}

  • Method: GET
  • Parameters:
    • group-id: The identifier of the class/group associated with the bucket
    • bucket-id: The identifier (UUID) of the bucket itself, as returned by /badgerstate/join
    • timestamp: The POSIX timestamp (in microseconds) that all returned results must be newer than
  • Response Type: application/json
  • Description: Responds with a JSON array of all data that was uploaded to the bucket after timestamp. The values in the JSON array are JSON objects of the form { "value": <string>, "timestamp": <number> }.
  • Error Conditions:
    • group-id is missing or empty (HTTP 422)
    • bucket-id is missing or an invalid UUID (HTTP 422)
    • timestamp is missing or an invalid number (HTTP 422)

/badgerstate/n-data/{{group-id}}/{{bucket-id}}/{{n}}

  • Method: GET
  • Parameters:
    • group-id: The identifier of the class/group associated with the bucket
    • bucket-id: The identifier (UUID) of the bucket itself, as returned by /badgerstate/join
    • n: The number of data updates to be returned (starting with the most recent);
  • Response Type: application/json
  • Description: Responds with a JSON array of the latest n entries in the bucket. If 0 is given for n, the response will contain all of the data in the bucket. The values in the JSON array are JSON objects of the form { "value": <string>, "timestamp": <number> }.
  • Error Conditions:
    • group-id is missing or empty (HTTP 422)
    • bucket-id is missing or an invalid UUID (HTTP 422)
    • n is missing or not a non-negative integer (HTTP 422)

/badgerstate/signal/{{group-id}}/{{bucket-id}}/{{signal}}

  • Method: POST
  • Parameters:
    • group-id: The identifier of the class/group associated with the bucket
    • bucket-id: The identifier (UUID) of the bucket itself, as returned by /badgerstate/join
    • signal: The arbitrary signal to be stored
  • Response Type: text/plain
  • Description: Stores the data on the server for future retrieval. Unlike with /badgerstate/data, each bucket has at most one signal. Responds with the POSIX timestamp (in microseconds) for when the data was added to the database.
  • Error Conditions:
    • group-id is missing or empty (HTTP 422)
    • bucket-id is missing or an invalid UUID (HTTP 422)
    • signal is missing or empty (HTTP 422)

/badgerstate/signal/{{group-id}}/{{bucket-id}}

  • Method: GET
  • Parameters:
    • group-id: The identifier of the class/group associated with the bucket
    • bucket-id: The identifier (UUID) of the bucket itself, as returned by /badgerstate/join
  • Response Type: text/plain
  • Description: Responds with a string of format <timestamp> | <signal>. It is highly advised that you check the check the timestamp on the signal for staleness before reacting to the signal.
  • Error Conditions:
    • group-id is missing or empty (HTTP 422)
    • bucket-id is missing or an invalid UUID (HTTP 422)
    • There has not yet been a signal stored for this bucket (HTTP 404)

Clone this wiki locally