Properties of a REST API method document

Purpose

Describe the purpose of the API method, add Key points (if necessary)

Logic

Description of the working algorithm of the API method and the interaction of services with each other add Service logic (if necessary)This method allows to create new contract employee record for existing contract with GB_CBP type through the NHS IT system

Logic

WS creating new contract employee

Configuration parameters

Description of the configuration parameters that are used when processing a request in the system

Dictionaries

Provides a list of links to dictionaries that are available in Confluence

Input parameters

Description of input parameters

Request structure

See on API-specification (посилання на сторінку з API-специфікацією)

Description of the REST API request structure, example

{
  "staff_units": 1,
  "declaration_limit": 2000,
  "employee_id": "ce050c01-f4a5-4d5f-85d6-7e41d41146bf",
  "division_id": "62d0a654-2e7f-40fb-b1bb-8a38cdc3f701",
  "contract_id": "6bb64748-7707-4be8-86e0-56cfb08e9b88",
  "start_date": "2018-04-20T19:14:13Z",
  "end_date": "2019-04-20T19:14:13Z"
}

Headers

Request data validation

...

Describe the process of checking the input data transmitted in the request for compliance with the given rules and restrictions set in the API

Processing

A list of processes related to receiving, changing or transmitting data according to the logic defined in the REST API

Response structure examples

The following attributes must be validated

1. Validate employee_id

   1. Check that employee exist and is_active = true

      1. in case of error return 404 error $.employee_id ('Employee is not found')

   2. Check that employee_id correspond to contractor legal entity through employees.legal_entity_id=contracts.contractor_legal_entity_id

      1. in case of error return 422 error $.employee_id ('Employee is not correspond to contractor legal entity')

2. Validate division_id

   1. Check that division exist and is_active = true

      1. in case of error return 404 error $.division_id ('Division is not found')

   2. Check that division_id correspond to contractor legal entity through divisions.legal_entity_id=contracts.contractor_legal_entity_id

      1. in case of error return 409 error $.division_id ('Division is not correspond to contractor legal entity')

3. Validate contract_id

   1. Check that contract exist and is_active = true and type = GB_CBP

      1. in case error return 409 error $.contract_id ('Contract must be an active and with GB_CBP type')

Validate request

1. Only authenticated and authorized user can use this service

2. Contract employee must be valid and consistent, i.e. all "foreign keys" must be valid

Processing

1. Set system attributes

1. Store to DB

1. Audit log (trigger logic)

Response structure examples

See on API-specification (посилання на сторінку з API-специфікацією)

Description of the REST API response structure, example

{
  "meta": {
    "code": 201,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": {
    "id": "8be63914-a278-470b-b868-1af5b9087332",
    "staff_units": 1,
    "declaration_limit": 2000,
    "employee_id": "ce050c01-f4a5-4d5f-85d6-7e41d41146bf",
    "division_id": "62d0a654-2e7f-40fb-b1bb-8a38cdc3f701",
    "contract_id": "6bb64748-7707-4be8-86e0-56cfb08e9b88",
    "start_date": "2018-04-20T19:14:13Z",
    "end_date": "2019-04-20T19:14:13Z",
    "is_active": true,
    "inserted_at": "2017-04-20T19:14:13Z",
    "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e",
    "updated_at": "2017-04-20T19:14:13Z",
    "updated_by": "2922a240-63db-404e-b730-09222bfeb2dd"
  }
}

HTTP status codes

Post-processing processes

Description of actions performed on data after processing

Technical modules where the method is used

List of pages describing technical modules where the method is used

...