-
Notifications
You must be signed in to change notification settings - Fork 0
Links
Links describe a message from one Device to another, containing a URL which should be opened on the receiving Device.
The Link resource is represented in responses under the links property. The links property will be an array of Links.
Links appear as follows:
{
"id": uint64,
"url": {
"id": uint64,
"first_seen": datetime,
"sent_counter": int64,
"address": string,
},
"unread": bool,
"time_read": datetime,
"sender": uint64,
"receiver": uint64,
"comment": string,
"sent": datetime
}
Mutable properties are properties that can be modified through interactions with the API.
- url.address: The URL that the receiving Device should open.
- unread: True if the Link has not been marked as read by the receiving Device yet, False or omitted if the Link has been marked as read by the receiving Device.
- comment: An optional comment that will be displayed on the Device that received the Link.
Immutable properties are properties that are created and modified only by the system; there is no way to modify them through the API.
- id: A unique, immutable identifier for this link.
- url.id: A unique, immutable identifier that corresponds to the URL being sent. This is used for grouping URLs that are sent through the system multiple times.
- url.first_seen: The timestamp from when the URL was first sent through the system, expressed according to RFC 3339.
- url.sent_counter: The number of times the URL has been sent through the system. This will be updated over time.
- sender: The ID of the Device that sent the Link. This will be pulled from the From header.
- receiver: The ID of the Device that the Link was sent to.
- time_read: The date and time the Link was marked as read by the receiving Device, expressed according to RFC 3339.
- sent: The date and time the Link was first sent by the sending Device, expressed according to RFC 3339.
If the User authenticating the request owns the Device whose Links are being listed, this request only requires authentication. If the User authenticating the request does not own the Device whose Links are being listed, this request requires administrative authentication.
GET /users/{username}/devices/{id}/links
The following URL parameters are accepted when listing Users, and will filter the list accordingly:
- after: the ID of a Link. Only Links sent after that Link will be returned.
- before: the ID of a Link. Only Links sent before that Link will be returned.
- count: the maximum number of Links to return, as an integer. Defaults to 20, with a maximum of 100.
This request sets the Last-Modified header to the latest sent or time_read property of the Links returned, whichever is greater.
The Content-Type of this request will be links/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be links/json.
This request returns a list of Link resources as a JSON array:
{
"code": 200,
"msg": "Successfully retrieved a list of links",
"links": [
{
// See the Link Resource for the contents of this part
},
{
// See the Link Resource for the contents of this part
}
]
}
In the event no links are to be returned, an empty array will be returned.
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | Username was not specified in the URL. |
| 400 | ERROR_INVALID_VALUE | role | role param was set to a value besides "sender" or "receiver" |
| 400 | ERROR_INVALID_FORMAT | after | after param was set to a non-integer value. |
| 400 | ERROR_INVALID_FORMAT | before | before param was set to a non-integer value. |
| 400 | ERROR_INVALID_FORMAT | count | count param was set to a non-integer value. |
| 400 | ERROR_INVALID_VALUE | count | count param was set to a value less than 1 or greater than 100. |
| 403 | ERROR_ACCESS_DENIED | Authenticating user does not have access to the specified user's links. | |
| 404 | ERROR_NOT_FOUND | user | Specified user not found. |
| 500 | ERROR_ACT_OF_GOD | Internal server error. | |
| 400 | ERROR_INVALID_FORMAT | device | Device param was set to a non-integer value. |
| 404 | ERROR_NOT_FOUND | device | Device was not found. |
| 400 | ERROR_WRONG_OWNER | device | Specified device does not belong to specified user. |
If the User authenticating the request is the User whose Links are being listed, this request only requires authentication. If the User authenticating the request is not the User whose Links are being listed, this request requires administrative authentication.
GET /users/{username}/links
The following URL parameters are accepted when listing Users, and will filter the list accordingly:
- after: the ID of a Link. Only Links sent after that Link will be returned.
- before: the ID of a Link. Only Links sent before that Link will be returned.
- count: the maximum number of Links to return, as an integer. Defaults to 20, with a maximum of 100.
This request sets the Last-Modified header to the latest sent or time_read property of the Links returned, whichever is greater.
The Content-Type of this request will be links/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be links/json.
This request returns a list of Link resources as a JSON array:
{
"code": 200,
"msg": "Successfully retrieved a list of links",
"links": [
{
// See the Link Resource for the contents of this part
},
{
// See the Link Resource for the contents of this part
}
]
}
In the event no links are to be returned, an empty array will be returned.
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | Username was not specified in the URL. |
| 400 | ERROR_INVALID_VALUE | role | role param was set to a value besides "sender" or "receiver" |
| 400 | ERROR_INVALID_FORMAT | after | after param was set to a non-integer value. |
| 400 | ERROR_INVALID_FORMAT | before | before param was set to a non-integer value. |
| 400 | ERROR_INVALID_FORMAT | count | count param was set to a non-integer value. |
| 400 | ERROR_INVALID_VALUE | count | count param was set to a value less than 1 or greater than 100. |
| 403 | ERROR_ACCESS_DENIED | Authenticating user does not have access to the specified user's links. | |
| 404 | ERROR_NOT_FOUND | user | Specified user not found. |
| 500 | ERROR_ACT_OF_GOD | Internal server error. |
This request requires only authentication if it is run against a Link that belongs to the authenticating User. If it is run against another User's Link, it requires administrative credentials.
GET /users/{username}/devices/{id}/links/{id}
This request sets the Last-Modified header to the sent property of the Link returned, or the time_read property of the Link returned, if it is set.
The Content-Type of this request will be links/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be links/json.
This request returns a list of Link resources as a JSON array. The array will only have one item:
{
"code": 200,
"msg": "Successfully retrieved link information",
"links": [
{
// See the Link Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | Username was not specified in the URL. |
| 403 | ERROR_ACCESS_DENIED | Authenticating user does not have access to the specified user's links. | |
| 404 | ERROR_NOT_FOUND | user | Specified user not found. |
| 500 | ERROR_ACT_OF_GOD | Internal server error. | |
| 400 | ERROR_MISSING_PARAM | device | device param was not set. |
| 400 | ERROR_INVALID_FORMAT | device | Device param was set to a non-integer value. |
| 404 | ERROR_NOT_FOUND | device | Device was not found. |
| 400 | ERROR_WRONG_OWNER | device | Specified device does not belong to specified user. |
| 400 | ERROR_MISSING_PARAM | id | link param was not set. |
| 400 | ERROR_INVALID_FORMAT | id | link param was set to a non-integer value. |
| 404 | ERROR_NOT_FOUND | link | Link was not found. |
| 400 | ERROR_WRONG_OWNER | link | Specified link does not belong to specified device. |
This request requires only authentication if the receiving Device belongs to the authenticating User. If it is sending a Link to another User's Device, it requires administrative credentials.
POST /users/{username}/devices/{id}/links
The request body should be a JSON array of Link Resources. Only the Mutable Properties will be used; the rest will be ignored.
A sample request body:
{
"links": [
{
"url": {
"address": "http://www.2cloud.org",
},
"comment": "Best service ever."
}
]
}
The request responds with the Links that were sent.
This request sets the Last-Modified header to the latest sent property of the Links returned.
The Content-Type of this request will be links/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be links/json.
This request returns a list of Link resources as a JSON array. The array will be contain the Links that were created:
{
"code": 201,
"msg": "Successfully created links",
"links": [
{
// See the Link Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | Username was not specified in the URL. |
| 403 | ERROR_ACCESS_DENIED | User does not have access to the specified user's links. | |
| 404 | ERROR_NOT_FOUND | user | The specified user was not found. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 400 | ERROR_MISSING_PARAM | device | The device ID was not specified in the URL. |
| 400 | ERROR_INVALID_FORMAT | device | The device ID specified was not an unsigned integer. |
| 404 | ERROR_NOT_FOUND | device | The specified device was not found. |
| 400 | ERROR_WRONG_OWNER | device | The specified device does not belong to the specified user. |
| 400 | ERROR_BAD_REQUEST_FORMAT | The body of the request is not valid JSON. | |
| 400 | ERROR_MISSING_PARAM | link.url.address | The link is missing the address portion of the URL property. |
This request requires only authentication if it is run against a Link that was sent from or to a Device that belongs to the authenticating User. If it is run against another User's Device's Link, it requires administrative credentials.
PUT /users/{username}/devices/{id}/links/{id}
Because this request has a body, the Content-Type, and Content-Length headers need to be set.
The request body should be a Link Resource. Only the Mutable Properties will be used; the rest will be ignored. Furthermore, the url.address property will be ignored in this request.
A sample request body:
{
"link": {
"comment": "An updated comment."
}
}
This request sets the Last-Modified header to the sent property of the Link returned, or (if it is set) the time_read property of the Link returned.
The Content-Type of this request will be links/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be links/json.
This request returns a list of Link resources as a JSON array. The array will only have one item—the Link that was modified:
{
"code": 200,
"msg": "Successfully updated the link",
"links": [
{
// See the Link Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | Username was not specified in the URL. |
| 400 | ERROR_MISSING_PARAM | device | Device ID was not specified in the URL. |
| 400 | ERROR_INVALID_FORMAT | device | Device ID was not an unsigned integer. |
| 400 | ERROR_MISSING_PARAM | id | Link ID was not specified in the URL. |
| 400 | ERROR_INVALID_FORMAT | id | Link ID was not an unsigned integer. |
| 400 | ERROR_BAD_REQUEST_FORMAT | Request body was not valid JSON. | |
| 500 | ERROR_ACT_OF_GOD | An unexpected error was encountered. | |
| 403 | ERROR_ACCESS_DENIED | User does not have access to the specified user's links. | |
| 404 | ERROR_NOT_FOUND | user | The specified user was not found. |
| 404 | ERROR_NOT_FOUND | device | The specified device was not found. |
| 400 | ERROR_WRONG_OWNER | device | The specified device does not belong to the specified user. |
| 404 | ERROR_NOT_FOUND | link | The specified link was not found. |
| 400 | ERROR_WRONG_OWNER | link | The specified link does not belong to the specified device. |
This request requires only authentication if it is run against a Link that was sent to a Device that belongs to the authenticating User. If it is run against another User's Device's Link, it requires administrative credentials.
DELETE /users/{username}/devices/{id}/links/{id}
This request sets the Last-Modified header to the sent property of the Link returned or (if it is set) the time_read property of the Link returned.
The Content-Type of this request will be links/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be links/json.
This request returns a list of Link resources as a JSON array. The array will only have one item—the Link that was just deleted:
{
"code": 200,
"msg": "Successfully deleted the link",
"links": [
{
// See the Link Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | Username was not specified in the URL. |
| 403 | ERROR_ACCESS_DENIED | User does not have access to the specified user's links. | |
| 404 | ERROR_NOT_FOUND | user | The specified user was not found. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 400 | ERROR_MISSING_PARAM | device | Device ID was not specified in the URL. |
| 400 | ERROR_INVALID_FORMAT | device | Device ID was not an unsigned integer. |
| 404 | ERROR_NOT_FOUND | device | Specified device was not found. |
| 400 | ERROR_WRONG_OWNER | device | Specified device does not belong to specified user. |
| 400 | ERROR_MISSING_PARAM | id | Link ID not specified in URL. |
| 400 | ERROR_INVALID_FORMAT | id | Link ID specified was not an unsigned integer. |
| 404 | ERROR_NOT_FOUMD | id | Specified link was not found. |
| 400 | ERROR_WRONG_OWNER | id | Specified link does not belong to the specified device. |