Machine Events

Machine Events scheme

An event is registered as a change of machine state, the stopping of a machine after a defect is detected for example. The event is identified by a unique id, and has a required parameter of machine on which the event has occured. Additional parameters are operator working the machine at the time (retrieved from access_token) of the event and optional JSON object for other parameters. The time of the event is registered when the request is made.

Scheme:

{
  "id": "UUID",
  "name": "String",
  "desc": "String",
  "machine": "UUID",
  "machine_state": "UUID",
  "operator_id": "UUID",
  "created_at": "String",
  "optional": "JSON"
}

Example machine event:

{
  "id": "ae54af76-964f-4ed8-8700-793b2ed5c20b",
  "name": "Stopping the machine",
  "desc": "Machine was stopped for unknown reasons",
  "machine": "0fc6d020-7f96-4424-9005-9e691d9c90e5",
  "machine_state": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
  "operator_id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "created_at": "2015-04-12 11:04:44 CET",
  "optional": {}
}

GET methods

GET /api/machines/:machine_id/events

Returns all events registered for a specific machine with :machine_id if any exist. If no events are registered for that specific machine a response contains an empty collection. The response can be a 404 if no machine resource is found. 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/0fc6d020-7f96-4424-9005-9e691d9c90e5/events 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": "ae54af76-964f-4ed8-8700-793b2ed5c20b",
    "name": "Stopping the machine",
    "desc": "Machine was stopped for unknown reasons",
    "machine": "0fc6d020-7f96-4424-9005-9e691d9c90e5",
    "machine_state": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
    "operator_id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
    "created_at": "2015-04-12 11:04:44 CET",
    "optional": {}
  },
  {
    "id": "c228b656-e2b6-42b0-ae51-40e977dabc75",
    "name": "Starting the machine",
    "desc": "Machine was put in function after the repair",
    "machine": "0fc6d020-7f96-4424-9005-9e691d9c90e5",
    "machine_state": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
    "operator_id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
    "created_at": "2015-04-12 11:24:12 CET",
    "optional": {}
  }
]
Parameters:
  • machine (string) – machine’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
  • page (integer) – page number, 10 resources per page are returned, default is 1
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 event
  • name (string) – name of the event
  • desc (string) – description of the event
  • machine (string) – id of the machine on which the event was registered
  • machine_state (string) – new state of the machine
  • operator_id (string) – operator that registered the event
  • created_at (string) – timestamp of when the event was registered
  • optional (string) – optional JSON object for other event parameters
Status Codes:
GET /api/machines/:machine_id/events/:id

Returns a specific event with :id registered for a specific machine if it exists, otherwise returns 404 error.

Example request:

GET /api/machines/0fc6d020-7f96-4424-9005-9e691d9c90e5/events/ae54af76-964f-4ed8-8700-793b2ed5c20b HTTP/1.1
Host: |localhost|

Example response:

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

{
  "id": "ae54af76-964f-4ed8-8700-793b2ed5c20b",
  "name": "Stopping the machine",
  "desc": "Machine was stopped for unknown reasons",
  "machine": "0fc6d020-7f96-4424-9005-9e691d9c90e5",
  "machine_state": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
  "operator_id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "created_at": "2015-04-12 11:04:44 CET",
  "optional": {}
}
Parameters:
  • machine (string) – machine’s unique id
  • id (string) – event’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Response JSON Object:
 
  • id (string) – id of a event
  • name (string) – name of a event
  • desc (string) – description of a event
  • machine (string) – id of the machine on which the event was registered
  • machine_state (string) – new state of the machine
  • operator_id (string) – operator that registered the event
  • created_at (string) – timestamp of when the event was registered
  • optional (string) – optional JSON object for other event parameters
Status Codes:

POST methods

POST /api/machines/:machine_id/events

Adds a new event associated with machine identified by :machine_id. Event id is generated server-side. Name and description are non unique string fields for additional information. operator_id identifies the operator working on the machine when the event occured. created_at field is generated server-side. Additional parameters can be saved in the optional field as a JSON object.

Example request:

POST /api/machines/0fc6d020-7f96-4424-9005-9e691d9c90e5/events HTTP/1.1
Host: |localhost|
Content-Type: application/json

{
  "name": "Stopping the machine",
  "desc": "Machine was stopped for unknown reasons",
  "machine": "0fc6d020-7f96-4424-9005-9e691d9c90e5",
  "machine_state": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
  "created_at": "2015-04-12 11:04:44 CET",
  "optional": {}
}

Example response:

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

{
  "id": "ae54af76-964f-4ed8-8700-793b2ed5c20b",
  "name": "Stopping the machine",
  "desc": "Machine was stopped for unknown reasons",
  "machine": "0fc6d020-7f96-4424-9005-9e691d9c90e5",
  "machine_state": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
  "operator_id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "created_at": "2015-04-12 11:04:44 CET",
  "optional": {}
}
Parameters:
  • machine (string) – machine’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Object:
 
  • name (string) – event’s name
  • desc (string) – event’s description
  • machine_state (string) – new state of the machine
  • optional (json) – optional event parameters
Response JSON Object:
 
  • id (string) – id of a event
  • name (string) – name of a event
  • desc (string) – description of a event
  • machine (string) – id of the machine on which the event was registered
  • machine_state (string) – new state of the machine
  • operator_id (string) – operator that registered the event
  • created_at (string) – timestamp of when the event was registered
  • optional (string) – optional JSON object for other event parameters
Status Codes:

PUT methods

PUT /api/machines/:machine_id/events/:event_id

Updates an existing event with new information, responds with the updated event information or error.

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/0fc6d020-7f96-4424-9005-9e691d9c90e5/events/ae54af76-964f-4ed8-8700-793b2ed5c20b HTTP/1.1
Host: |localhost|
Content-Type: application/json

{
  "name": "Stopping the machine",
  "desc": "Machine was stopped for unknown reasons",
  "machine_state": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
  "operator_id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "created_at": "2015-04-12 11:04:44 CET",
  "optional": {}
}

Example response:

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

{
  "id": "ae54af76-964f-4ed8-8700-793b2ed5c20b",
  "name": "Stopping the machine",
  "desc": "Machine was stopped for unknown reasons",
  "machine": "0fc6d020-7f96-4424-9005-9e691d9c90e5",
  "machine_state": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
  "operator_id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "created_at": "2015-04-12 11:04:44 CET",
  "optional": {}
}
Parameters:
  • machine (string) – machine’s unique id
  • id (string) – event’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Object:
 
  • desc (string) – event’s description
  • name (string) – event’s name
  • machine_state (string) – new state of the machine
  • created_at (string) – event’s creating time (note: this value should not be modified)
  • optional (json) – optional event parameters
  • machine_state – new state of the machine
Response JSON Object:
 
  • id (string) – id of a event
  • name (string) – name of a event
  • desc (string) – description of a event
  • machine (string) – id of the machine on which the event was registered
  • operator_id (string) – operator that registered the event
  • created_at (string) – timestamp of when the event was registered
  • optional (string) – optional JSON object for other event parameters
Status Codes:

DELETE methods

DELETE /api/machines/:machine_id/events/:id

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

Example request:

DELETE /api/machine/0fc6d020-7f96-4424-9005-9e691d9c90e5/event/ae54af76-964f-4ed8-8700-793b2ed5c20b HTTP/1.1
Host: |localhost|

Example response:

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