AMCS Group CustomerSiteHealthAndSafetyBlob API

openapi: 3.2.0
info:
  title: AMCS Platform REST Customer Site Health And Safety Blob API
  description: '![latest End points](/amcsrestapi/diagram/endpointslatest.svg)


    # Overview


    ## Who Should Read this Document


    This document contains a technical description of the AMCS Platform REST API. It is intended for:


    · System integrators


    · Customer IT team looking to integrate AMCS Platform with another system


    · Third parties looking to integrate their system with AMCS Platform


    ## Document Scope


    This document introduces the technical aspects of the AMCS Platform REST API. The purpose of this document is to provide readers with detail on how to:


    · Access the REST API


    · Make calls to the API to retrieve, append and update resources


    · Retrieve the incremental changes to a collection


    · Find more detail on the end points that are available from an environment. ## Summary


    AMCS Platform REST API is designed to support the integration of AMCS Platform with other systems. With care and additional infrastructure, the REST API can be used to build functionality on top of Platform but that is not it’s primary purpose. The ‘changes since’ process provides the main means of performing an initial synchronisation of the AMCS Platform and another system, and then keeping them synchronised. Methods are also provided to create and update resources. # Integration Patterns and Tools


    The AMCS Platform provides a number of tools that can be used to connect systems. Care should be taken to match the right tooling to the intended pattern of integration. · When an extract-based approach is needed, use BI reporting. · When derived values are require, use the data mart. · When business processes on different systems need to be integrated by synchronising the data on each through an event style interface, use the REST API. An integration using the REST API will need to take full responsibility for all aspects of the integration including:


    · Pulling change events from AMCS Platform


    · Filtering the changed resources for the ones that are of interest


    · Pulling additional resources from the REST API in order the retrieve all the properties needed by the destination


    · Mashing resources to create the complete view required


    · Translating that into the form required by the destination


    · Validating this to ensure it meet the entry rules of the destination


    · Pushing the result to the destination


    In the early stages of designing the interface care should be taken to ensure that the need for caching/staging has been considered. The changes since functionality is effectively a means of pulling create/change events from platform. The only filters available enable retrieval of related resources to build a view external to AMCS Platform


    # Basics


    The AMCS REST API provides a RESTful interface that allows access to the primary business resources of the AMCS platform. The interface follows general HATEOAS compliance principles. ## Quick start


    A quickstart walkthrough based on node.js and covering authentication and getting a page of customers can be found here. ## Interface definitions


    Swagger documentation for the end points available on an environment can be found at:


    Before 8.5: https://{environment domain name}/swagger/ui/index


    From 8.5: https://{environment domain name}/erp/api/swagger/ui/index


    ## HTTP Interface


    The following HTTP RESTful methods are provided as part of this API:


    · GET: Provides read access to retrieve details of one or more resources. · POST: Creates or updates a single resource or a set of resources. · PUT: Updates a single resource or a set of resources. Note:


    · DELETE methods are currently not provided as part of the API. The REST API URIs begin with


    https://{environment domain name}/erp/api/integrator/erp


    For example:

    https://prod.amcs-at-mycompany.com/erp/api/integrator/erp


    This should be used as the base of the URI.'
  version: latest
servers:
- url: https://ete-p5-tst-svc-core.amcsplatform.com/erp/api/integrator/erp
tags:
- name: CustomerSiteHealthAndSafetyBlob
paths:
  /blobs/customerSiteHealthAndSafetyBlobs:
    post:
      tags:
      - CustomerSiteHealthAndSafetyBlob
      summary: Create or update
      description: '| ------------------------------------- | ----------------------------------------------------------------------------- | -------- |

        | Guid| The GUID associated to the Customer Site Health and Safety blob| No |

        | MediaContentBase64| The Image/PDF converted to base 64| Yes |

        | DocumentName| The Document Name| Yes |

        | DocumentReference| The Document Reference| Yes |

        | DocumentDescription| The Document Description| No |

        | RelatedCustomerSiteGuid| The Related Customer Site Guid| Yes |

        | HealthAndSafetyDocumentTypeListItem | The GUID and description of the health and safety document type| Yes |

        | ValidFrom| The valid from date| Yes |

        | ValidUntil| The valid until date| No |

        | IsHighRisk| Whether the document contains high risk items| No |

        | IsSentToVehicle| Whether the document is sent to vehicle| No |


        **Extra validations**


        | Condition | Error message |

        | --------- | ------------- |

        | DocumentName is Null or not provided | The mandatory property DocumentName has a null value. The request could not be processed. Supply a value for the DocumentName property of the submitted resource. |

        | DocumentName has less than 5 characters or more than 100 characters | CustomerSiteHealthAndSafetyForm has the property DocumentName with value of {DocumentName} that is not supported. DocumentName should be at least 1 character and at most 100 characters, excluding the extension |

        | DocumentName does not have any of pdf/png/jpg/gif extension | CustomerSiteHealthAndSafetyForm has the property DocumentName with value of {DocumentName} that is not supported. DocumentName should have any of pdf/png/jpg/gif extension |

        | DocumentReference is Null or not provided | The mandatory property DocumentReference has a null value. The request could not be processed. Supply a value for the DocumentReference property of the submitted resource. |

        | RelatedCustomerSiteGuid is Null or not provided | The mandatory property RelatedCustomerSiteGuid has a null value. The request could not be processed. Supply a value for the RelatedCustomerSiteGuid property of the submitted resource. |

        | Invalid RelatedCustomerSiteGuid | Failed to retrieve Customer Site with RelatedCustomerSiteGuid of {Guid} |

        | HealthAndSafetyDocumentTypeListItem.Guid is Null or not provided | The mandatory property HealthAndSafetyDocumentTypeListItem.Guid has a null value. The request could not be processed. Supply a value for the HealthAndSafetyDocumentTypeListItem.Guid property of the submitted resource.

        | Invalid HealthAndSafetyDocumentTypeListItem.Guid | Failed to retrieve HealthAndSafetyDocumentType with HealthAndSafetyDocumentTypeListItem.Guid of {Guid} |

        | MediaContentBase64 is Null or not provided | The mandatory property MediaContentBase64 has a null value. The request could not be processed. Supply a value for the MediaContentBase64 property of the submitted resource. |

        | MediaContentBase64 is not a valid base64 string | Failed to save/update CustomerSiteHealthAndSafetyForm because ImageContentHash has Invalid length for a Base-64 char array or string |


        ## Information

        | Information |

        | ----------- |

        | Currently we are only validating for a valid base64 string, we are not validating the string against the file extension |'
      operationId: CustomerSiteHealthAndSafetyBlob_Create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiIntegratorHealthAndSafetyBlobHashesResource'
        required: true
        x-bodyName: null
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResourceId'
components:
  schemas:
    ApiResourceId:
      type: object
      properties:
        resource:
          type: string
          format: uuid
        errors:
          $ref: '#/components/schemas/ApiResourceErrors'
        status:
          $ref: '#/components/schemas/ApiResourceStatus'
    ApiIntegratorListItemResource:
      type: object
      properties:
        Description:
          type: string
        Guid:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
    ApiIntegratorHealthAndSafetyBlobHashesResource:
      type: object
      properties:
        MediaContentBase64:
          type: string
        DocumentName:
          type: string
        DocumentReference:
          type: string
        DocumentDescription:
          type: string
        HealthAndSafetyDocumentTypeListItem:
          $ref: '#/components/schemas/ApiIntegratorListItemResource'
        RelatedCustomerSiteGuid:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        ValidFrom:
          type: string
          format: localDate
          example: '2000-01-01'
        ValidUntil:
          type: string
          format: localDate
          example: '2000-01-01'
        IsHighRisk:
          type: boolean
        IsSentToVehicle:
          type: boolean
    ApiResourceStatus:
      type: object
      properties:
        id:
          type: integer
          format: int32
        isSuccess:
          type: boolean
    ApiResourceErrors:
      type: object
      properties:
        errors:
          type: string