componentNewsStream

Description

The NewsStreamServer provides a REST-Api such that users or other services can request news feeds. This is used to provide the users within the social network with information. The NewsStreamServer provides a news stream sorted ascending by time. The server's task is only to provide the news stream and to create new users, friendships and news stream items.

There will be various news stream item types allowed.

Requirements

• users should be able to create status updates to reach their social network
• users should be able to read status updates within their social network to react
• the news stream has to provide the possibility to filter the news stream items
• users should be able to comment to status updates from other users within their social network
• the news stream should support a varity of different status update types to support self publication, promotion and selling
• the news stream has to use authentification and respect the user's privacy
• the server has to provide an interface easy to use to enable authentificated, external users to receive content
• the server has to be highly performant
• the social network algorithm should be read optimized
• files should be stored at a separate server to relieve the news stream server
• the server should be configurable
• enable/disable status update types
• paths for files stored externally
• as the server depends on Graphity it has to be thread-safe

Protocol

The protocol is called "News Stream Server Protocol" or short "NSSP".

The typical CRUD operations are supported.

Status messages
For every operation there are human readable status messages naming the problem. In addition a second line includes a detailed description to support to solve the problem. In case multiple errors occurred only the first problem will be reported and the server will stop handling the request.

Create

Two ways to create data entries. One is for single entries (or rather small numbers sequentially).
The other one is for importing whole databases (so called "bulk import"). This allows streaming whole CSV-files instead of every single entry of it separately.

There are three different types of create requests, therefore each create request has to define the type of the request. You can create users, add follow edges to users and create status updates.

As long as the server does not support OAuth you need to provide the identifier of the user requesting.

So the basic parameters are

• type: determining the request type (String)
• user_id: specifying the requesting user's identifier (long) [will be ommitted when OAuth is supported]

Create a user

To create a user pass "user" as the type of the create request. Anything else is undefined yet.

Create a follow edge

To create a follow edge to a user pass "follow" as the type of the create request. In addition you need to specify which user you want to create the edge to. The edge will add this user to the social network of the user requesting.

Specific parameters

• followed_id: specifying the identifier of the user the new follow edge shall lead to (long)

Status messages

• "ok" if everything succeeded
• "user identifier invalid" if the identifier of the user requesting is invalid
• "type invalid" if the create type is invalid
• "followed identifier invalid" if the identifier of the user the edge shall lead to is invalid
• "follow edge existing" if there is already a follow edge to the user specified

Example

HTTP/1.0 POST somedomain/stream/create
Content-type: multipart/form-data, boundary=AaB03x

--AaB03x
content-disposition: form-data; name="user_id"

12345
--AaB03x
content-disposition: form-data; name="type"

follow
--AaB03x
content-disposition: form-data; name="followed_id"

1337
--AaB03x--

Create a status update

To create a status update pass "status_update" as the type of the create request. In addition you need to specify the identifier and the type of the status update, as there may exist various status update templates registered in the server. This template may lead to several other parameters necessary to create the status update.
For example a simple template for text-only status updates could require a parameter named "message" holding the message that should be displayed.

Specific parameters

• status_update_id: specifying the status update identifier (String)
• status_update_type: specifying the status update template used (String)
• { ... } various parameters determined by the status update template used

Status messages

• "ok" if everything succeeded
• "user identifier invalid" if the identifier of the user requesting is invalid
• "type invalid" if the create type is invalid
• "status update identifier invalid" if the status update identifier is already in use
• "status update type invalid" if the status update template is unknown
• "status update instantiation failed" if the parameters passed did not match the status update template specified

Example

HTTP/1.0 POST somedomain/stream/create
Content-type: multipart/form-data, boundary=AaB03x

--AaB03x
content-disposition: form-data; name="user_id"

12345
--AaB03x
content-disposition: form-data; name="type"

status_update
--AaB03x
content-disposition: form-data; name="status_update_type"

text
--AaB03x
content-disposition: form-data; name="message"

Hello World
--AaB03x--

Read

To read status updates you need to pass two parameters.
As long as the server does not support OAuth you need to provide the identifier of the user requesting. Then pass the identifier of the user whose status update you want to retrieve. You also need to define how many news feed items should be retrieved. A flag to switch between the retrieval of status updates for the user, from his/her social network, and from the user, meaning the update items he/she created.

Parameters

• user_id: specifying the requesting user's identifier (long) [will be ommitted when OAuth is supported]
• poster_id: specifying the identifier of the user whose status update you want to retrieve
• num_items: defining how many news feed items should be retrieved (int)
• own_updates: 0 to retrieve status updates for the user (notice: this will also be recognized if the requesting user accesses his own stream), 1 to retrieve status updates from the user (int)

Status messages

• JSON matching Activitystrea.ms representing the news stream accessed, if everything succeeded
• "user identifier invalid" if the identifier of the user requesting is invalid
• "poster identifier invalid" if the identifier of the user whose status update you want to retrieve is invalid
• "number of items invalid" if the number of items passed is invalid
• "retrieval flag invalid" if the flag for own updates is invalid

Example

HTTP/1.0 GET somedomain/stream/read?user_id=12345&num_items=15&own_updates=0

Update

The news stream server does not provide updates yet.

Delete

There are three different types of delete requests, therefore each delete request has to define the type of the request. You can delete users, delete follow edges to users and delete status updates.

As long as the server does not support OAuth you need to provide the identifier of the user requesting.

So the basic parameters are

• type: determining the request type (String)
• user_id: specifying the requesting user's identifier (long) [will be ommitted when OAuth is supported]

Delete a user

To delete a user pass "user" as the type of the delete request. Anything else is undefined yet.

Delete a follow edge

To delete a follow edge to a user pass "follow" as the type of the delete request.
In addition you need to specify which user you want to delete the edge from. The deletion will remove this user from the social network of the user requesting.

Specific parameters

• followed_id: specifying the identifier of the user the existing follow edge leads to (long)

Status messages

• "ok" if everything succeeded
• "user identifier invalid" if the identifier of the user requesting is invalid
• "type invalid" if the delete type is invalid
• "followed identifier invalid" if the identifier of the user the edge leads to is invalid
• "follow edge not existing" if there is no follow edge to the user specified

Example

HTTP/1.0 POST somedomain/stream/delete
Content-type: multipart/form-data, boundary=AaB03x

--AaB03x
content-disposition: form-data; name="user_id"

12345
--AaB03x
content-disposition: form-data; name="type"

follow
--AaB03x
content-disposition: form-data; name="followed_id"

815
--AaB03x--

Delete a status update

To delete a status update pass "status_update" as the type of the delete request. In addition you need to specify the identifier of the status update you want to delete.

Specific parameters

• status_update_id: specifying the identifier of the status update that shall be deleted (long)

Status messages

• "ok" if everything succeeded
• "user identifier invalid" if the identifier of the user requesting is invalid
• "type invalid" if the delete type is invalid
• "status update identifier invalid" if the status update identifier is invalid
• "status update not owned" if the status update is not owned by the user requesting

Example

HTTP/1.0 POST somedomain/stream/delete
Content-type: multipart/form-data, boundary=AaB03x

--AaB03x
content-disposition: form-data; name="user_id"

12345
--AaB03x
content-disposition: form-data; name="type"

status_update
--AaB03x
content-disposition: form-data; name="status_update_id"

12345678
--AaB03x--

Features

Status Update Templates

Example

<class name="Plain" version="1.0">
  <param name="message" type="String" />
</class>

Technologies

• Java
• neo4j
• Activitystrea.ms

Responsible Developer

Sebastian