Skip to content
This repository has been archived by the owner on Feb 24, 2020. It is now read-only.

Links

Jump to bottom
Paddy Foran edited this page Mar 12, 2013 · 9 revisions

Links describe a message from one Device to another, containing a URL which should be opened on the receiving Device.

The Link Resource

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

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

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.

Listing Links By Device

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.

Request Format

Endpoint

GET /users/{username}/devices/{id}/links

Optional Parameters

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.

Response Format

Header

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.

Body

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.

Errors

  • Username not specified
  • After not a valid ID
  • Before not a valid ID
  • Count not a number
  • User does not have access to specified user's links
  • Specified user not found
  • Device ID not a valid ID
  • Device not found
  • Specified device does not belong to specified user

Listing Links By 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.

Request Format

Endpoint

GET /users/{username}/links

Optional Parameters

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.

Response Format

Header

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.

Body

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.

Errors

  • Username not specified
  • After not a valid ID
  • Before not a valid ID
  • Count not a number
  • User does not have access to specified user's links
  • Specified user not found

Getting Information About A Link

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.

Request Format

Endpoint

GET /users/{username}/devices/{id}/links/{id}

Response Format

Header

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.

Body

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
    }
  ]
}

Errors

  • Username not specified
  • User not found
  • User does not have access to specified username's links
  • Device ID not specified
  • Device ID not valid
  • Device not found
  • Specified device does not belong to specified user
  • Link ID not specified
  • Link ID not valid
  • Link not found

Creating New Links

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.

Request Format

Endpoint

POST /users/{username}/devices/{id}/links

Request Body

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."
		}
	]
}

Response Format

The request responds with the Links that were sent.

Header

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.

Body

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
    }
  ]
}

Errors

  • Username not specified
  • User not found
  • User does not have access to specified username's links
  • Device ID not specified
  • Device ID not valid
  • Device not found
  • Specified device does not belong to specified user
  • Badly-formed JSON
  • Link is missing address field

Updating A Link's Information

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.

Request Format

Endpoint

PUT /users/{username}/devices/{id}/links/{id}

Request Headers

Because this request has a body, the Content-Type, and Content-Length headers need to be set.

Request Body

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."
  }
}

Errors

  • Username not specified
  • User not found
  • User does not have access to specified username's links
  • Device ID not specified
  • Device ID not valid
  • Device not found
  • Specified device does not belong to specified user
  • Badly-formed JSON
  • Link ID not specified
  • Link ID not valid
  • Link not found

Response Format

Header

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.

Body

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
    }
  ]
}

Deleting A Link

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.

Request Format

Endpoint

DELETE /users/{username}/devices/{id}/links/{id}

Response Format

Header

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.

Body

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
    }
  ]
}

Errors

  • Username not specified
  • User not found
  • User does not have access to specified username's links
  • Device ID not specified
  • Device ID not valid
  • Device not found
  • Specified device does not belong to specified user
  • Link ID not specified
  • Link ID not valid
  • Link not found
Clone this wiki locally