doc/api/reference/devices.rst

   1 .. _devices-api:
   2
   3 Devices API
   4 ===========
   5
   6 Devices are used throughout the API to identify a device / a client
   7 application. A device ID can be any string matching the regular expression
   8 ``[\w.-]+``. The client application MUST generate a string to be used as its
   9 device ID, and SHOULD ensure that it is unique within the user account. A good
  10 approach is to combine the application name and the name of the host it is
  11 running on.
  12
  13 The API maintains subscriptions per device ID. Two distinct devices using the
  14 same ID might receive (from their point of view) incomplete information.  While
  15 it is possible to retrieve a list of devices and their IDs from the server,
  16 this SHOULD NOT be used to let a user select an existing device ID.
  17
  18 Each device has exactly one type, which can be either *desktop*, *laptop*,
  19 *mobile*, *server* or *other*. When retrieving device information, clients
  20 SHOULD map unknown device types to *other*. Clients MUST NOT send
  21 different device types that those previously stated.
  22
  23
  24 Resources
  25 ---------
  26
  27 The Devices API defines the following resources ::
  28
  29     /user/<username>/devices
  30     /user/<username>/device/<device-id>
  31
  32
  33 Retrieve Device List
  34 --------------------
  35
  36 Retrieve the list of existing devices ::
  37
  38     GET /user/<username>/devices
  39     Content-Type: application/json
  40
  41     200 OK
  42     TODO: headers
  43
  44     {
  45         "username": "username",
  46         "devices": [
  47             {
  48                 "id": "mynotebook",
  49                 "caption": "gPodder on my Notebook",
  50                 "type": "laptop",
  51                 "subscriptions": 10
  52             }
  53         ]
  54     }
  55
  56
  57 Get Device Information
  58 ----------------------
  59
  60 Retrieve information about a specific device ::
  61
  62     GET /user/<username>/device/<device-id>
  63     Content-Type: application/json
  64
  65     200 OK
  66     TODO: headers
  67
  68     {
  69         "id": "mynotebook",
  70         "caption": "gPodder on my Notebook",
  71         "type": "laptop",
  72         "subscriptions": 10
  73     }
  74
  75 404 is returned if no such device exists.
  76
  77
  78 Update Device Information
  79 -------------------------
  80
  81 Update the information of a device ::
  82
  83     POST /user/<username>/device/<device-id>
  84     Content-Type: application/json
  85
  86     TODO response: return device information
  87
  88 The body of the request MUST contain a JSON object that can contain the fields
  89 *caption* and *type*. The information stored on the server will be updated with
  90 the provided values. Fields not included in the request will not be updated.
  91
  92 If no device with the specified Id exists, a new device is created. Default
  93 values are used for missing fields.