macemoth / tapasstandards

Repository containing standards for HSG's tapas project in the fall semester 2021

Tapas Engineering Task Force 👀

This documents defines common Tapas APIs.

Interaction Scheme

⬅️➡️ denotes a JSON Object and its direction of sending.

Auction

AuctionHouse (offering)		AuctionHouse (bidding)
	Auction ➡️ (over AuctionStartedEvent via Message Queue*)	HTTP POST @ /auction
HTTP POST @ /bid	⬅️ Bid
	Task ➡️	HTTP POST @ /taskwinner

* The message queue is offered either by MQTT or PubSubHub.

Task Execution

TaskList (offering)		Bidding party (undefined endpoint)
HTTP PATCH @ /tasks/<task-UUID>	⬅️ TaskPatch (State.ASSIGNED)
		(Executes task)
HTTP PATCH @ /tasks/	⬅️ TaskPatch (State.EXECUTED, OutputData)

Uniform HTTP API

Auction House

URL: tapas-auction-house.<publicIP>.nio.io

Port: 8085

HTTP POST /auction

Media-Type application/auction+json

Body:

{
  "auctionId": "1",
  "auctionHouseUri": "https://127.0.0.1:8085/",
  "taskUri":"http://example.org/tasks/cef2fa9d-367b-4e7f-bf06-3b1fea35f354",
  "taskType":"COMPUTATION",
  "deadline":"2021-12-24 12:00:00"
}

• Note that deadline is produced by using Java's default toString() method of the java.sql.Timestamp class
• The taskUri should not only contain the server, but also the /tasks/<task-UUID>, s.t. the original Task can be fetched

Response Codes

No codes defined as messages are sent by queue

No response body

HTTP POST /bid

Media-Type application/bid+json

Body:

{
  "auctionId":"1",
  "bidderName":"Group1",
  "bidderAuctionHouseUri":"http://example.com/",
  "bidderTaskListUri":"http://example.com/tasks/"
}

Response Codes

• 204 (No content) Bid was received and accepted
• 404 (Not found) There never was an auction with that <auctionID>
• 410 (Gone) The Auction that was requested has already expired

No response body

HTTP POST /taskwinner

Media-Type application/task+json

Body (Identical to Task):

{
  "taskId":"cef2fa9d-367b-4e7f-bf06-3b1fea35f354",
  "taskName":"task1",
  "taskType":"COMPUTATION",
  "taskStatus":"ASSIGNED",
  "originalTaskUri":"http://example.org/tasks/cef2fa9d-367b-4e7f-bf06-3b1fea35f354",
  "serviceProvider":"tapas-group1",
  "inputData":"1+1",
  "outputData":"2"
}

Response Codes

• 202 (Accepted) The won task is accepted and can be done
• 406 (Not Acceptable) The winning Auction House cannot execute the won task anymore

No response body

HTTP POST /tasks/<taskId> (on tapas-tasks)

Media-Type application/json-patch+json

Body: See tapas-tasks documentation

Response Codes

• 200 (Accepted) The patch was applied to the Task
• 404 (Not Found) The Task requested to patch wasn't found
• 406 (Not acceptable) An invalid patch request was made

Response Body For debugging purposes, the patched Task is returned.

HTTP GET /discovery/ (on tapas-auction-house)

Notes

• There is no request body
• The response's task types are the ones that are sought, i.e. that cannot be executed locally (this way, the crawling auction house should subscribe to the discovered auction house if it can offer that service)

Media-Type application/auctionhousediscovery+json

Response Codes

• 200 (Accepted) The request was received.

Response Body

  {
  "auctionHouseInfo": [
    {
      "auctionHouseUri":"http://example.org",
      "webSubUri":"http://example.org",
      "taskTypes":["COMPUTATION", "RANDOMTEXT"],
      "timeStamp":"2021-12-24 12:00:00",
      "groupName":"Group3"
    },
    {
      "auctionHouseUri":"http://facemash.com",
      "webSubUri":"http://facemash.com",
      "taskTypes":["BIGROBOT"],
      "timeStamp":"2021-12-24 12:00:00",
      "groupName":"Group2"
    }
  ]
  }

Task Types (with in- and outputs)

BIGROBOT

(Cherrybot or PretendABot)

Input: None

Output: None

SMALLROBOT

(Leubot)

Input: None

Output: None

COMPUTATION

Input: <OPERAND> <OPERATOR> <OPERAND>

Output: Integer result of computation

Valid Operands: All integers

Valid Operators: +, -, *

RANDOMTEXT

Input: None

Output: Randomly generated sentence

HUMIDITY

Input: None

Output: The measured humidity in percent

TEMPERATURE

Input: None

Output: The measured temperature in degrees celsius