Skip to content

REST

Jump to bottom Edit New page
Matt Bierner edited this page Aug 31, 2015 · 60 revisions

The Blot're REST API provides a familiar HTTP based, request/response set of operations. The REST API is best suited for querying the current state of Blot're and performing transactional update operations. Some operations may require user authorization.

It is strongly recommended that realtime applications use the websocket based subscription API instead of polling the REST API. You can use subscriptions and the REST API together too. For convenience, or if the overhead of a REST based API is a concern, you can also perform many of the same query and updates over a web socket with the web socket response API.

Stream Operators

Stream

GET api/stream/ID

Get a stream.

Example

https://blot.re/v0/api/stream/552f25793004785713de6750

{
  "id": "552f68963004ce448e1e19a5",
  "name": "ToasterPrime",
  "uri": "toastmastergeneral/toasterprime",
  "created": 1429170326262,
  "updated": 1429170326262,
  "status": {
    "color": "#0000ff",
    "created": 1429170326262,
    "poster": "552f24f33004785713de674e"
  },
  "tags": [{"tag": "toaster", {"tag": "energoncubebreakfast"}],
  "owner": "552f24f33004785713de674e"
}

Errors

  • 404 - The stream does not exist.

GET api/stream

Get multiple streams. The Default behavior is to return most recently updated streams.

Params

  • Optional query - If provided, used to search streams. Regular string search by stream names, while queries prefixed with # search by tag or status.

Example

https://blot.re/v0/api/stream?query=toast

[{
  "id": "552f68963004ce448e1e19a5",
  "name": "ToasterPrime",
  "uri": "toastmastergeneral/toasterprime",
  "created": 1429170326262,
  "updated": 1429170326262,
  "status": {
    "color": "#0000ff",
    "created": 1429170326262,
    "poster": "552f24f33004785713de674e"
  },
  "tags": [{"tag": "toaster"}, {"tag": "energoncubebreakfast"}],
  "owner": "552f24f33004785713de674e"
}, {
  "id": "5550fcc9300496217de54ebf",
  "name": "Deceptitoast",
  "uri": "sirbakealot/deceptitoast",
  "created": 1429170326262,
  "updated": 1429170326262,
  "status": {
    "color": "#000000",
    "created": 1429170326262,
    "poster": "5550f2a63004a531be8820c5"
  },
  "tags": [{"tag": "thetoastisalie"}, {"tag": "energoncubebreakfast"}],
  "owner": "5550f2a63004a531be8820c5"
}]

PUT api/stream 

{
  "name": NEW_STREAM_NAME,
  "uri": NEW_STREAM_URI,
  ?"status": STATUS,
  ?"tags": [TAGS...]
}

Create a new stream. An optional initial status can also be provided. Requires authorization.

Root streams cannot be created, every stream must be the hierarchal child of an existing stream. The parent stream is derived from the uri of the new stream. The requesting user must have ownership of the parent stream.

If the stream already exists, attempts to update the status if one is provided. Returns 200 if the stream exists and the update was successful and 201 if a new stream was created.

Example

https://blot.re/v0/api/stream
{
  "name": "toasterprime",
  "uri": "toastmastergeneral/toasterprime",
  "status": {
     "color": "#0000ff"
  },
  "tags": [{"tag": "toaster"}, {"tag": "energoncubebreakfast"}]
}

{
  "id": "552f68963004ce448e1e19a5",
  "name": "ToasterPrime",
  "uri": "toastmastergeneral/toasterprime",
  "created": 1429170326262,
  "updated": 1429170326262,
  "status": {
    "color": "#0000ff",
    "created": 1429170326262,
    "poster": "552f24f33004785713de674e"
  },
  "tags": [{"tag": "toaster"}, {"tag": "energoncubebreakfast"}]
  "owner": "552f24f33004785713de674e"
}

Errors

  • 401 - User does not own the parent stream.
  • 404 - Parent stream does not exist.
  • 422 - Stream name and uri do not match.
  • 422 - Stream name is not valid.

DELETE api/stream/ID

Delete a stream. Requires authorization.

This automatically removes this stream from all relationships and deletes all its hierarchical children.

Root streams cannot be deleted.

Errors

  • 401 - User does not own the stream.
  • 404 - Stream does not exist.
  • 422 - Cannot delete root streams.

GET api/stream/ID/status

Gets the status of a stream.

Example

https://blot.re/v0/api/stream/552f25793004785713de6750/status

{
  "color": "#0000ff",
  "created": 1429160419760,
  "poster": "552f24f33004785713de674e"
}

Errors

  • 404 - The stream does not exist.

POST api/stream/ID/status 

{
  "color": COLOR_IN_HEX
}

Update the status of an existing stream. Requires authorization.

Requesting user must have ownership of the stream.

Example

POST https://blot.re/v0/api/stream/552f25793004785713de6750/status
{
  "color": "#0000ff"
}

{
  "color": "#0000ff",
  "created": 1429160419760,
  "poster": "552f24f33004785713de674e"
}

Errors

  • 401 - User does not own the stream.
  • 404 - Stream does not exist.
  • 400/422 - Invalid data.

GET api/stream/ID/children

Returns an array of all child streams.

Params

  • query - Optional. Filters children by name. For example, query=to would match children like to, toster, and lotto
  • limit - Optional int. Maximum number of children to return.
  • offset - Optional int. Offset to start selecting children at.

Example

https://blot.re/v0/api/stream/553d7e6f30043b38ce3f7050/children

[{
  "id": "553dc3c630043b38ce3f7056",
  "name": "Toasthalla",
  "uri": "toastmastergeneral/toasthalla“,
  "created": 1430111174510,
  "updated": 1430111174510,
  "status": {
    "color": "#dda520",
    "created": 1430111174510,
    "poster": "553d7e6b30043b38ce3f704e"
  },
  "tags": [{"tag": "sotoast"}, {"tag": "goldenbrown"}, {"tag": "challahorgy"}],
  "owner": "553d7e6b30043b38ce3f704e"
}, {
  "id": "553dc3c130043b38ce3f7054",
  "name": "Strategic Butter Reserve",
  "uri": "toastmastergeneral/strategic+butter+reserve",
  "created": 1430111169478,
  "updated": 1430111169478,
  "status": {
    "color": "#111111",
    "created": 1430111169478,
    "poster": "553d7e6b30043b38ce3f704e"
  },
  "tags": [{"tag": "toastworldproblems"}],
  "owner": "553d7e6b30043b38ce3f704e"
}]

Errors

  • 404 - Stream does not exist.

GET api/stream/ID/children/CHILD_ID

Look up a child by id. Can be used to check the existence of a child.

Example

http://localhost:9000/v0/api/stream/553d7e6f30043b38ce3f7050/children/553dc3c130043b38ce3f7054

{
  "id": "553dc3c130043b38ce3f7054",
  "name": "Strategic Butter Reserve",
  "uri": "toastmastergeneral/strategic+butter+reserve",
  "created": 1430111169478,
  "updated": 1430111169478,
  "status": {
    "color": "#111111",
    "created": 1430111169478,
    "poster": "553d7e6b30043b38ce3f704e"
  },
  "tags": [{"tag": "toastworldproblems"}],
  "owner": "553d7e6b30043b38ce3f704e"
}

Errors

  • 404 - Stream does not exist.
  • 404 - Child does not exist.

PUT api/stream/ID/children/CHILD_ID

Register a new child. Requires authorization.

Returns 200 if the child already existed and 201 if a new child was created.

This does not create a child stream, only registers an existing child with a parent stream. Streams are automatically registered as children with their hierarchical parent when created.

Example

http://localhost:9000/v0/api/stream/553d7e6f30043b38ce3f7050/children/552f25793004785713de6750

{
  "id": "552f25793004785713de6750",
  "name": "child1",
  "uri": "user/child1",
  "created": 1429153145591,
  "updated": 1429160419760,
  "status": {
    "color": "#0000ff",
    "created": 1429160419760,
    "poster": "552f24f33004785713de674e"
  },
  "owner": "552f24f33004785713de674e"
}

Errors

  • 401 - User does not have permission to edit parent stream.
  • 404 - Stream does not exist.
  • 404 - Requested child stream does not exist.
  • 422 - Parent cannot be its own child.
  • 422 - The parent has too many children.

DELETE api/stream/ID/children/CHILD_ID

Delete child. Requires authorization.

This only removes the parent child relationship, it does not delete the child stream. Returns 200 if successful.

Errors

  • 401 - User does not have permission to edit parent stream.
  • 404 - Parent does not exist.
  • 404 - Child does not exist.
  • 422 - Cannot remove hierarchical child. For example, the stream sub1 at user/sub1 cannot be removed as a child of user.

GET api/stream/ID/tags

Gets the tags of a stream.

Example

https://blot.re/v0/api/stream/553dc3c630043b38ce3f7056/tags

[
  {"tag": "sotoast"},
  {"tag": "goldenbrown"},
  {"tag": "challahorgy"}
]

Errors

  • 404 - The stream does not exist.

POST api/stream/ID/tags

Sets the tags of a stream, overwriting the existing tags. Requires authorization. Returns the set of normalized tags values.

Example

https://blot.re/v0/api/stream/553dc3c630043b38ce3f7056/tags
[
  {"tag": "RYE"},
  {"tag": "Pumpernickel"},
  {"tag": "Challahorgy"}
]

[
  {"tag": "rye"},
  {"tag": "pumpernickel"},
  {"tag": "challahorgy"}
]

Errors

  • 404 - The stream does not exist.
  • 401 - User does not have permission to edit stream.
  • 400 - Too many tags.
  • 400 - Invalid tag data.

GET api/stream/ID/tags/TAG

Lookup a specific tag on a stream.

Example

GET https://blot.re/v0/api/stream/553dc3c630043b38ce3f7056/tags/GoldenBrown

{"tag": "goldenbrown"}

Errors

  • 404 - The stream does not exist.
  • 404 - The tag does not exist.

PUT api/stream/ID/tags/TAG

Add a specific tag to a stream. Requires authorization. Returns 200 if the tag already existed or 201 if the tag was successfully added.

Example

PUT https://blot.re/v0/api/stream/553dc3c630043b38ce3f7056/tags/GoldenBrown

{"tag": "goldenbrown"}

Errors

  • 404 - The stream does not exist.
  • 401 - User does not have permission to edit stream.
  • 400 - Too many tags.
  • 400 - Invalid tag name.

DELETE api/stream/ID/tags/TAG

Remove a tag from a stream. Requires authorization. Returns the deleted tag.

Example

DELETE https://blot.re/v0/api/stream/553dc3c630043b38ce3f7056/tags/RYE

{"tag": "rye"}

Errors

  • 401 - User does not have permission to edit stream.
  • 404 - The stream does not exist.
  • 404 - The tag does not exist.
Add a custom footer
Add a custom sidebar
Clone this wiki locally