-
Notifications
You must be signed in to change notification settings - Fork 0
ThingBroker API old
The Thing Broker can be accessed through a RESTFul interface running on either Tomcat or a Springsource server, generally running on port 8080. On the examples below we will use an instance running on the server at "http://kimberly.magic.ubc.ca:8080". This will vary if you deployed your own instance. Currently, Thing Broker has only been implemented with JSON. That is, most data and "thing" definitions are accepted by the server only as JSON objects, and all responses will be in JSON format.
The Thing Broker abstract entities as "things" with a name, decription and type. "Things" can have state and events related to them. Generally, developers would register a "thing" with the Thing Broker, and add data, metadata or related events to it. Then if needed they would query this information using the REST API.
A "thing" object is represented by the JSON object:
{
thingId: "88c67d4e-178e-4c50-98b2-3e2179e32636",
name: "Ricardo-Galaxy-Nexus",
description: "Description for a thing",
type: "smartphone",
metadata: null,
followers: [ ],
following: [ ],
state: null
}
An "event" response is commonly represented by a collection of events ordered by timestamp:
[
{
eventId: "b7ba0f87-d54f-4531-af93-d78277b305ee",
thingId: "123",
serverTimestamp: 1349912663503,
info: null,
data: [
"1abe3a85-7376-4a15-968b-72dca3fef2e6"
]
},
{
eventId: "62e5d0fe-a854-4d72-bbec-6a211f720671",
thingId: "123",
serverTimestamp: 1349911561470,
info: null,
data: [
"9dafb29b-21c8-4266-a6d6-8fe5ae128470"
]
},
{
eventId: "5c114a70-7fb2-42ae-9685-9738d1008651",
thingId: "123",
serverTimestamp: 1349911236601,
info: "{"website":"www.blueyou.com.br"}",
data: [ ]
}
]
You can use the publicly available endpoint of the Thing Broker at:
http://kimberly.magic.ubc.ca:8080/thingbroker/
If you are running your own instance exchange the location of the broker to your server. The following methods are available for creating and manipulating "things" on the Thing Broker.
This method creates a thing on the Thing Broker. There are no required JSON parameters, but you MUST provide an empty JSON object; that is, at least "{}"
http://kimberly.magic.ubc.ca:8080/thingbroker/thing
none
thingId: (not required) Specifies an alpha-numeric id.If not provided, thingId will receive a UUID as the identifier
name: (not required) Specifies a thing's name.
description: (not required) Specifies a short description of the thing.
type: (not required) Specifies a user-defined thing type. Example Values: sensor, display, mobile.
POST http://kimberly.magic.ubc.ca:8080/thingbroker/thing
Content-type: application/JSON Body: {"thingId": "123", "name": "test","description":"This is a thing","type":"Random thing"}
{
"thingId": "123",
"name": "test",
"description": "This is a thing",
"type": "Random thing",
"metadata": null,
"followers": [],
"following": [],
"state": null
}
This method updates a thing on the Thing Broker. The only required JSON parameter is ThingId.
http://kimberly.magic.ubc.ca:8080/thingbroker/thing
none
thingId: (required) Specifies an alpha-numeric id that identifies a thing
name: (not required) Specifies a thing's name.
description: (not required) Specifies a short description of the thing.
type: (not required) Specifies a user-defined thing type. Example Values: sensor, display, mobile.
PUT http://kimberly.magic.ubc.ca:8080/thingbroker/thing
Content-type: application/JSON Body: {"thingId": "123", "name": "test","description":"This is a thing","type":"Random thing"}
{
"thingId": "123",
"name": "test",
"description": "This is a thing",
"type": "Random thing",
"metadata": null,
"followers": [],
"following": [],
"state": null
}
This method removes a thing and all its events from Thing Broker.
http://kimberly.magic.ubc.ca:8080/thingbroker/thing
thingId: (required) Specifies an alpha-numeric id that identifies a thing
none
DELETE http://kimberly.magic.ubc.ca:8080/thingbroker/thing?thingId="123"
Response: A JSON that represents the thing it was removed.
{
"thingId": "123",
"name": "test",
"description": "This is a thing",
"type": "Random thing",
"metadata": null,
"followers": [],
"following": [],
"state": null
}
This method will search for a thing on the current Thing Broker instance. It will return a thing object.
http://kimberly.magic.ubc.ca:8080/thingbroker/thing/search
thingId: Search for a thing whose id matches "thingId"
name: Search for all things whose name matches "name"
type: Seach for all things whose type matches "type"
Note: It's also possible to compose a search with more than one parameter
none
GET http://kimberly.magic.ubc.ca:8080/thingbroker/thing/search?thingId=123
GET http://kimberly.magic.ubc.ca:8080/thingbroker/thing/search?name=test
GET http://kimberly.magic.ubc.ca:8080/thingbroker/thing/search?type=test
GET http://kimberly.magic.ubc.ca:8080/thingbroker/thing/search?thingId=123&name=test
{
thingId: "123",
name: "test",
description: "This is a thing",
type: "Random thing",
metadata: null,
followers: [ ],
following: [ ],
state: null
}
This method will add events to a thing,
http://kimberly.magic.ubc.ca:8080/thingbroker/events/event/thing/{thingId}
keep-stored: (required) When set to "true" the events will be stored for future reference.
You must provide a JSON object containing a collection of key-value pairs. You can provide as many key-value pairs, like so:
{"video_url": "http://www.youtube.com/watch?v=QH2-TGUlwu4"}
POST http://kimberly.magic.ubc.ca:8080/thingbroker/events/event/thing/123?keep-stored=true
Content-type: application/JSON Body: {"video_url": "http://www.youtube.com/watch?v=Rku5Oyf-hYU"}
Note: If you are adding a file (image or other) on the body, make sure to change the content-type appropriately to: "Content-type: multipart/form-data". In this case, there'll be a reference id to each content in the data field of the event
{
"eventId": "7eb4e2ea-448f-4a5a-a388-0babc8b502c9",
"thingId": "123",
"serverTimestamp": 1349932703681,
"info": "{\"video_url\":\"http://www.youtube.com/watch?v=Rku5Oyf-hYU\"}",
"data": []
}
This method will query events from a thing, responding with an ordered collection of events. Events will be ordered by timestamp.
http://kimberly.magic.ubc.ca:8080/thingbroker/events/thing/{thingId}
requester (required) Defines who is requesting events. It's used to automatically subscribe the requester to the thing which the events will be returned.
timeout (not required) Determines, in seconds, how long the request will last until return. It's used to receive realtime events.
limit: (not required) Determines how many events will be fetched. Example Values: 24
start: (not required) Works together with "end", returns events in an interval of time defined by "start" and "end". This parameter must be defined in Unix epoch time (milliseconds). Example Values: 1349937425
end: (not required) Works together with "start", returns events in an interval of time defined by "start" and "end". This parameter must be defined in Unix epoch time (milliseconds). Example Values: 1349937434
before: (not required) Returns events preceeding a time defined by this parameter. This parameter must be defined in Unix epoch time (milliseconds). Example Value: 1349937434
after: (not required) Returns events suceeding a time defined by this parameter. This parameter must be defined in Unix epoch time (milliseconds). Example Value: 1349937420
**Note: If you don't provide url parameters it'll be returned a maximum of 25 events stored in Thing Broker
none
GET http://kimberly.magic.ubc.ca:8080/thingbroker/events/thing/123?requester=1234
[
{
eventId: "62e5d0fe-a854-4d72-bbec-6a211f720671",
thingId: "123",
serverTimestamp: 1349911561470,
info: null,
data: [
"9dafb29b-21c8-4266-a6d6-8fe5ae128470"
]
},
{
eventId: "5c114a70-7fb2-42ae-9685-9738d1008651",
thingId: "123",
serverTimestamp: 1349911236601,
info: "{"website":"www.blueyou.com.br"}",
data: [ ]
},
{
eventId: "8f769677-a6f7-429d-b19b-db0c409e016c",
thingId: "123",
serverTimestamp: 1349906908431,
info: "{"video_url":"http://www.youtube.com/watch?v=Rku5Oyf-hYU"}",
data: [ ]
}
]
This method will retrieve a piece of content by the unique content ID. Such ID is unique only to the Thing Broker instance being queried. Uniqueness between different Thing Broker servers cannot be guaranteed
http://kimberly.magic.ubc.ca:8080/thingbroker/events/event/content/{contentId}
mustAttach: (required) Indicated if the content must be attached to the response (for downloading purpose) or not.
none
The server will respond with the file whose ID matches the provided id.
None
This method will update the event identified by eventId. If none event was found, it returns a JSON with an error message
http://kimberly.magic.ubc.ca:8080/thingbroker/events/event/{eventId}
serverTimestamp: (required) The serverTimestamp field for the event that is being updated. This is necessary to check if the event being updated won't overlap new changes in the event.
none
POST http://kimberly.magic.ubc.ca:8080/thingbroker/events/event/{eventId}?serverTimestamp=18746875687
Note: If you are adding a file (image or other) on the body, make sure to change the content-type appropriately to: "Content-type: multipart/form-data". In this case, there'll be a reference id to each content in the data field of the event
The server will respond with a JSON describing the updated event.
None
This method will add content to the info field of the event identified by eventId. If none event was found, it returns a JSON with an error message If you try to add content with an already existing key, the new content will overlap the one that is already stored.
http://kimberly.magic.ubc.ca:8080/thingbroker/events/event/{eventId}
serverTimestamp: (required) The serverTimestamp field for the event that is being updated. This is necessary to check if the event being updated won't overlap new changes in the event.
none
PUT http://kimberly.magic.ubc.ca:8080/thingbroker/events/event/{eventId}?serverTimestamp=18746875687
The server will respond with a JSON describing the updated event.
None
Calling a service in thing broker can return a JSON representing a status message indicating an error that occurred. All status messages are composed by a status code and a text message. The status code can be:
OK = 0
THING_NOT_FOUND = 1
THING_ALREADY_REGISTERED = 2
SENT_EVENT_TO_NON_EXISTENT_THING = 3
REQUESTER_NOT_INFORMED = 4
REQUESTER_NOT_REGISTERED = 5
EVENT_NOT_FOUND = 6
EVENT_DATA_NOT_FOUND = 7
INVALID_EVENT_INFO_FIELD = 8
SERVER_TIMESTAMP_NOT_PROVIDED = 9
SERVER_TIMESTAMP_OUTDATED = 10
INTERNAL_ERROR = 500
{
"code": 1,
"message": "Thing not found"
}