REST API --- DRAFT ---¶

Method definitions to the Components Database.

• All methods conform to REST
• The security for all method calls will be done through personal certificates (tokens in the future, when SCD switches).
• Every method at a minimum returns a status. The status will either be "GOOD" or contain an error message.

NOTE: We are considering removing the field "update" from all methods as this application only inserts records.

• Table of contents
• REST API --- DRAFT ---
  • COMPONENT TYPES
    • /component-types[?[page=<int>][&term=<pattern>]]
    • /component-types
    • /component-types/<name>[?history=true]
  • COMPONENTS
    • /component-types/<name>/components[?[page=<int>][&term=<pattern>]]
    • /component-types/<name>/components
    • /components/<external-id>[?history=true]
    • /components/<external-id>/container[?history=true]
    • /components/<external-id>/subcomponents[?history=true]
  • TEST TYPES
    • /component-types/<name>/test-types
    • /component-types/<name>/test-types
    • /component-types/<type-name>/test-types/<test-type-name>[?history=true]
  • TESTS
    • /components/<external-id>/tests[?history=true]
    • /components/<external-id>/tests
    • /components/<external-id>/tests/<test-name>[?history=true]
  • OPERATIONS
    • /structures[?page=<int>]
    • /structures/<external-id>[?history=true]
    • /structures/<external-id>
  • CABLES
    • /cables[?page=<int>]
    • /cables/<external-id>[?history=true]
    • /cables/<external-id>

COMPONENT TYPES¶

/component-types[?[page=<int>][&term=<pattern>]]¶

• Method: GET
• Returns the list of current type definitions w/o the detailed specs. May require page number if the total number of records exceeds some limit. TBD

returns attributes
{
    "status": string,
    "output": [json, json,...],
    "pagination": {
      "next": URL, 
      "page": <int>, 
      "pages": <int>, 
      "prev": URL
    },
    "link": {
      "href": URL, 
      "rel": "self" 
    } 
}

/component-types¶

• Method: POST
• Inserts a new component type attribute definition.
  • Updates to a database record are NOT supported. Meaning, a complete attribute definition must be provided each time a record is inserted.
  • The latest inserted record is considered current.

send attributes
{
    "name": string,
    "definition":  json,
    "comments": string,
    "update": boolean    (default false) 

}

returns attributes
{
    "status": string
}

/component-types/<name>[?history=true]¶

• Method: GET
• Returns the current attribute definition of a specific component type. Includes prior attribute definitions if requested.

returns attributes
{
    "status": string,
    "output": [json, json,...],
    "link": {
      "href": URL, 
      "rel": "self" 
    } 
}

COMPONENTS¶

/component-types/<name>/components[?[page=<int>][&term=<pattern>]]¶

• Method: GET
• Returns the list of components for the specified type w/o the detailed specs. May require page number if the total number of records exceeds some limit. TBD
• Optional filtering by external-id substring

returns attributes
{
    "status": string,
    "output": [json, json,...],
    "pagination": {
      "next": URL, 
      "page": <int>, 
      "pages": <int>, 
      "prev": URL
    },
    "link": {
      "href": URL, 
      "rel": "self" 
    } 
}

/component-types/<name>/components¶

• Method: POST
• Inserts a new component and component attributes record.
  • Updates to a database record are NOT supported. Meaning, all attribute fields must be provided each time a record is inserted.
  • The latest inserted attributes record is considered current.

send attributes
{
    "external_id": string,
    "definition": json,
    "comments": string,
    "update": boolean    (default false)
}

returns attributes
{
    "status": string
}

/components/<external-id>[?history=true]¶

• Method: GET
• Returns the current attributes for a specific component, will include all prior attributes if requested.

returns attributes
{
    "status": string,
    "output": json,
    "link": {
      "href": URL, 
      "rel": "self" 
    } 
}

/components/<external-id>/container[?history=true]¶

• Method: GET
• Returns the current container record for the component, if any. Will include historical records if requested.

returns attributes
{
    "status": string,
    "output": [json, json, ...],
    "link": {
      "href": URL, 
      "rel": "self" 
    } 
}

/components/<external-id>/subcomponents[?history=true]¶

• Method: GET
• Returns current subcomponents for a specific component. Will include historical children if requested.

returns attributes
{
    "status": string,
    "output": [json, json, ...],
    "link": {
      "href": URL, 
      "rel": "self" 
    } 
}

TEST TYPES¶

/component-types/<name>/test-types¶

• Method: GET
• Returns the list of all test types for the component type <name>

returns attributes
{
    "status": string,
    "output": [json, json, ...],
    "link": {
      "href": URL, 
      "rel": "self" 
    } 
}

/component-types/<name>/test-types¶

• Method: POST
• Creates the new test type definition for the component type <name>

send attributes
{
    "name": string,
    "definition": json,
    "comments": string,
    "update": boolean    (default false) 
}

returns attributes
{
    "status": string
}

/component-types/<type-name>/test-types/<test-type-name>[?history=true]¶

• Method: GET
• Returns the test type definition for the component type <type-name>. Also includes historical definitions if requested.

returns attributes
{
    "status": string,
    "output": [json, ...],
    "link": {
      "href": URL, 
      "rel": "self" 
    } 
}

TESTS¶

/components/<external-id>/tests[?history=true]¶

• Method: GET
• Returns the test results for this component. Also includes historical definitions if requested.

returns attributes
{
    "status": string,
    "output": [json, json, ...],
    "link": {
      "href": URL, 
      "rel": "self" 
    } 
}

/components/<external-id>/tests¶

• Method: POST
• Loads the results of a specific component test.

send attributes
{
    "testName": string,
    "attributes": json,
    "comments": string,
    "update": boolean    (default false)
}

returns attributes
{
    "status": string
}

/components/<external-id>/tests/<test-name>[?history=true]¶

• Method GET
• Returns the current results of a specific test. Also includes historical results if requested.

returns attributes
{
    "status": string,
    "testResults": [json, json, ...],
    "link": {
      "href": URL, 
      "rel": "self" 
    } 
}

OPERATIONS¶

/structures[?page=<int>]¶

• Method GET
• Returns the list of structure records. May require page number if the total number of records exceeds some limit. TBD

/structures/<external-id>[?history=true]¶

• Method GET
• Returns the last structure record for the component.

/structures/<external-id>¶

• Method POST

send attributes
{
    "container_external_id": string,
    "functional_position": string,
    "geo_location": string,
    "operation": string,
    "comments": string
}

returns attributes
{
    "status": string
}

CABLES¶

/cables[?page=<int>]¶

• Method GET
• Returns the list of cable structure records. May require page number if the total number of records exceeds some limit. TBD

/cables/<external-id>[?history=true]¶

• Method GET
• Returns the last structure record for the cable.

/cables/<external-id>¶

• Method POST

send attributes
{
    "external_id_a": string,
    "external_id_b": string,
    "geo_location": string,
    "operation": string,
    "comments": string
}

returns attributes
{
    "status": string
}