Defects

Defects scheme

Each defect is identified by its unique id. Additionally a defect is defined for a certain part identified by part_id. name and desc fields are non unique strings used for greater readability and additional information. The media_url field of the defect contains and URL to the media content of the defect that can be an image, video, text or other form of media. The comment field provides additional information about the defect. taxonomy field is a JSON object used to define different ways of categorizing defects and should be used when searching for similar defects, it is left to the client side to decide how to define this object, whether by using categories, tags, or other types of taxonomy.

Scheme:

{
  "id": "UUID",
  "part_id": "String",
  "name": "String",
  "desc": "String",
  "media_url": "String",
  "comment": "String",
  "taxonomy": "JSON"
}

Example defect:

{
  "id": "ae54af76-964f-4ed8-8700-793b2ed5c20b",
  "part_id": "optical_32",
  "name": "Poor surface quality",
  "desc": "The part presents a thin layer of plastic that seems less robust than needed",
  "media_url": "http://|localhost|/media/defect_1.jpg",
  "comment": "No obvious cause of this defect detected",
  "taxonomy": {
      "categories": "optical, mechanical"
  }
}

GET methods

GET /api/defects

Returns all defects 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.

A defect can be optionally filtered by part_id identifier of the production part on which the defect is present by adding it in the query.

Example request:

GET /api/defects 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",
                "part_id": "optical_32",
                "name": "Poor surface quality",
                "desc": "The part presents a thin layer of plastic that seems less robust than needed",
                "media_url": "http://|localhost|/media/defect_1.jpg",
                "comment": "No obvious cause of this defect detected",
                "taxonomy": {
                    "categories": "optical, mechanical"
                }
            },
            {
                "id": "0fc6d020-7f96-4424-9005-9e691d9c90e5",
                "part_id": "mechanical_13",
                "name": "Poor mechanical quality",
                "desc": "The part presents poor mechanical part that seems less robust than needed",
                "media_url": "http://|localhost|/media/defect_2.jpg",
                "comment": "No obvious cause of this defect detected",
                "taxonomy": {
                    "categories": "optical, mechanical"
                }
            }
]
Query Parameters:
 
  • page (integer) – page number, 10 resources per page are returned, default is 1
  • part_id (string) – id of the part for which defects are returned
  • 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 defect
  • part_id (string) – id of the part on which the defect was detected
  • name (string) – name of the defect
  • desc (string) – description of the defect
  • media_url (string) – URL location of media relative to the defect
  • comment (string) – comment regarding the defect
  • taxonomy (json) – taxonomy JSON object that puts defects in categories, tags or other type of classification
Status Codes:
GET /api/defects/:id

Returns a specific defect with :id and the rest of its parameters if it exists, otherwise returns 404 error.

Example request:

GET /api/defects/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",
        "part_id": "optical_32",
        "name": "Poor surface quality",
        "desc": "The part presents a thin layer of plastic that seems less robust than needed",
        "media_url": "http://|localhost|/media/defect_1.jpg",
        "comment": "No obvious cause of this defect detected",
        "taxonomy": {
            "categories": "optical, mechanical"
        }
    }
Parameters:
  • id (string) – defect’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Response JSON Object:
 
  • id (string) – id of the defect
  • part_id (string) – id of the part on which the defect was detected
  • name (string) – name of the defect
  • desc (string) – description of the defect
  • media_url (string) – URL location of media relative to the defect
  • comment (string) – comment regarding the defect
  • taxonomy (json) – taxonomy JSON object that puts defects in categories, tags or other type of classification
Status Codes:

POST methods

POST /api/defects

Adds a new defect with its part_id, name, desc, media_url, comment and taxonomy. id is generated server-side. Returns an URI location of the new resource or error message.

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

Example request:

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

{
        "part_id": "optical_32",
        "name": "Bad large dimensions",
        "desc": "The part presents greater length than specified",
        "media_url": "http://|localhost|/media/defect_large_dimension_optical_32.jpg",
        "comment": "No obvious cause of this defect detected",
        "taxonomy": {
            "categories": "dimension"
        }
}

Example response:

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

{
  "id": "ae54af76-964f-4ed8-8700-793b2ed5c20b",
  "part_id": "optical_32",
  "name": "Bad large dimensions",
  "desc": "The part presents greater length than specified",
  "media_url": "http://|localhost|/media/defect_large_dimension_optical_32.jpg",
  "comment": "No obvious cause of this defect detected",
  "taxonomy": {
    "categories": "dimension"
  }
}
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Object:
 
  • part_id (string) – part id on which defect was enccountered
  • name (string) – defect’s name
  • desc (string) – defect’s description
  • media_url (string) – URL to the media content rapresenting the defect
  • comment (string) – comment of the operator that encountered the defect
  • taxonomy (json) – taxonomy for categorizing defects
Response JSON Object:
 
  • id (string) – id of the defect
  • part_id (string) – id of the part on which the defect was detected
  • name (string) – name of the defect
  • desc (string) – description of the defect
  • media_url (string) – URL location of media relative to the defect
  • comment (string) – comment regarding the defect
  • taxonomy (json) – taxonomy JSON object that puts defects in categories, tags or other type of classification
Status Codes:

PUT methods

PUT /api/defects/:id

Updates an existing defect 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/defects/ae54af76-964f-4ed8-8700-793b2ed5c20b HTTP/1.1
Host: |localhost|
Content-Type: application/json

    {
        "part_id": "optical_32",
        "name": "Poor surface quality",
        "desc": "The part presents a thin layer of plastic that seems less robust than needed",
        "media_url": "http://|localhost|/media/defect_1.jpg",
        "comment": "Was caused by increasing temperature parameter by Jimmy",
        "taxonomy": {
            "categories": "optical, mechanical"
        }
    }

Example response:

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

{
    "id": "ae54af76-964f-4ed8-8700-793b2ed5c20b",
    "part_id": "optical_32",
    "name": "Poor surface quality",
    "desc": "The part presents a thin layer of plastic that seems less robust than needed",
    "media_url": "http://|localhost|/media/defect_1.jpg",
    "comment": "Was caused by increasing temperature parameter by Jimmy",
    "taxonomy": {
      "categories": "optical, mechanical"
    }
}
Parameters:
  • id (string) – defect’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Object:
 
  • part_id (string) – part id on which defect was enccountered
  • name (string) – defect’s name
  • desc (string) – defect’s description
  • media_url (string) – URL to the media content rapresenting the defect
  • comment (string) – comment of the operator that encountered the defect
  • taxonomy (json) – taxonomy for categorizing defects
Response JSON Object:
 
  • id (string) – id of the defect
  • part_id (string) – id of the part on which the defect was detected
  • name (string) – name of the defect
  • desc (string) – description of the defect
  • media_url (string) – URL location of media relative to the defect
  • comment (string) – comment regarding the defect
  • taxonomy (json) – taxonomy JSON object that puts defects in categories, tags or other type of classification
Status Codes:

DELETE methods

DELETE /api/defects/:id

Delete an existing defect, 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/defect/ae54af76-964f-4ed8-8700-793b2ed5c20b HTTP/1.1
Host: |localhost|

Example response:

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