Machines

Machines scheme

Each machine is identified by its unique id. name and desc fields are non unique strings used for greater readability and additional information. The state of the machine is an integer and identifies the current state of the machine. The optional parameter is a JSON object that contains information relevant to the machine, such as serial number, producer, various internal machine parameters, etc.

Scheme:

{
  "id": "UUID",
  "name": "String",
  "desc": "String",
  "state": "UUID",
  "optional": "JSON"
}

Example machine:

{
  "id": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
  "name": "Cool ice machine",
  "desc": "Machine used for cooling ice in the summer",
  "state": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "optional": {
    "serial_number" : 12345,
    "producer" : "icecream_factory",
    "machine_parameters": {
      "machine_parameter_01": 5,
      "machine_parameter_02": 2.3
    }
  }
}

GET methods

GET /api/machines

Returns all machines with their relative information if at least one resource exists, otherwise returns an empty collection. Request can contain a page parameter that returns a specific page, additionally total number of pages, next page, previous page and other information are described in the response header.

Example request:

GET /api/machines?page=1 HTTP/1.1
Host: |localhost|

Example response:

HTTP/1.1 200 OK
Content-type: application/json
X-Total: 2
X-Total-Pages: 1
X-Page: 1
X-Per-Page: 10

[
  {
    "id": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
    "name": "Cool ice machine",
    "desc": "Machine used for cooling ice in the summer",
    "state": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
    "optional": {
      "serial_number" : 12345,
      "producer" : "icecream_factory",
      "machine_parameters": {
        "machine_parameter_01": 5,
        "machine_parameter_02": 2.3
      }
    }
  },
  {
    "id": "07a6c0d7-e264-4576-9338-9eb4ce385490",
    "name": "Heat ice machine",
    "desc": "Machine used for heating ice in the winter",
    "state": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
    "optional": {}
  }
]
Query Parameters:
 
  • page (integer) – page number, 10 resources per page are returned, default is 1
  • access_token (string) – valid access token for OAuth2 authentication
Response Headers:
 
  • X-Total – total number of elements in the collection server-side
  • X-Total-Pages – total number of pages containing all elements
  • X-Page – current page that has been returned
  • X-Per-Page – number of elements per page
  • X-Next-Page – id of next page
  • X-Previous-Page – id of previous page
Response JSON Array of Objects:
 
  • id (string) – id of the machine
  • name (string) – name of the machine
  • desc (string) – description of the machine
  • state (string) – state id of the machine
  • optional (json) – optional JSON object for other machine parameters
Status Codes:
GET /api/machines/:id

Returns a specific machine with :id, its state and parameteres if it exists, otherwise returns 404 error.

Example request:

GET /api/machines/986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02 HTTP/1.1
Host: |localhost|

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
  "name": "Cool ice machine",
  "desc": "Machine used for cooling ice in the summer",
  "state": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "optional": {
    "serial_number" : 12345,
    "producer" : "icecream_factory",
    "machine_parameters": {
      "machine_parameter_01": 5,
      "machine_parameter_02": 2.3
    }
  }
}
Parameters:
  • id (string) – machine’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Response JSON Object:
 
  • id (string) – id of a machine
  • name (string) – name of a machine
  • desc (string) – description of a machine
  • state (string) – state id of a machine
  • optional (json) – optional JSON object for other machine parameters
Status Codes:

POST methods

POST /api/machines

Adds a new machine with its name, description and parameters. id is generated server-side. Returns an URI location of the new resource or error message.

Initially machine state is set to null, and can only be changed through POSTing a machine event with the new state.

Note: Do not execute twice the same POST request for it will create two resources with the same information.

Example request:

POST /api/machine HTTP/1.1
Host: |localhost|
Content-Type: application/json

{
  "name": "New machine 03",
  "desc": "Another new machine that does stuff",
  "optional": {}
}

Example response:

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "c228b656-e2b6-42b0-ae51-40e977dabc75",
  "name": "New machine 03",
  "desc": "Another new machine that does stuff",
  "state": null,
  "optional": {}
}
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Object:
 
  • name (string) – machine’s name
  • desc (string) – machine’s description
  • optional (json) – optional machine parameters
Response JSON Object:
 
  • id (string) – id of a machine
  • name (string) – name of a machine
  • desc (string) – description of a machine
  • state (string) – state id of a machine
  • optional (json) – optional JSON object for other machine parameters
Status Codes:

PUT methods

PUT /api/machines/:id

Updates an existing machine with new information. Returns an URI location of the new resource or error message.

Note: All parameters must be defined with the PUT request, ie. PUT request replaces the existing resource with the modified one if it exists, or creates a new one.

Example request:

PUT /api/machines/986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02 HTTP/1.1
Host: |localhost|
Content-Type: application/json

{
  "name": "Cool ice machine",
  "desc": "Machine used for cooling ice in the summer",
  "optional": {
    "serial_number" : 12345,
    "producer" : "icecream_factory",
    "machine_parameters": {
      "machine_parameter_01": 5,
      "machine_parameter_02": 2.3
    }
  }
}

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
  "name": "Cool ice machine",
  "desc": "Machine used for cooling ice in the summer",
  "state": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "optional": {
    "serial_number" : 12345,
    "producer" : "icecream_factory",
    "machine_parameters": {
      "machine_parameter_01": 5,
      "machine_parameter_02": 2.3
    }
  }
}
Parameters:
  • id (string) – machine’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Object:
 
  • name (string) – machine’s name
  • desc (string) – machine’s description
  • optional (json) – optional machine parameters
Response JSON Object:
 
  • id (string) – id of a machine
  • name (string) – name of a machine
  • desc (string) – description of a machine
  • state (string) – state id of a machine
  • optional (json) – optional JSON object for other machine parameters
Status Codes:

DELETE methods

DELETE /api/machines/:id

Delete an existing machine, responds with the confirmation or error. Can only delete one resource at a time, to remove a collection of machines call the DELETE method for each element.

Example request:

DELETE /api/machines/986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02 HTTP/1.1
Host: |localhost|

Example response:

HTTP/1.1 200 OK
Parameters:
  • id (integer) – machine’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Status Codes: