ADDED: Health check endpoints (requirement for Issue #2).

Author: balassy

.nycrc

@@ -8,6 +8,7 @@
     "**/*.spec.ts",
     "**/*.interfaces.ts",
     "src/cities/cities.ts",
+    "src/health/health.ts",
     "src/swagger/swagger.ts"
   ],
   "extension": [

README.md

@@ -29,6 +29,7 @@ This sample uses the [Serverless Application Framework](https://serverless.com/)
 - Test coverage report with [Istanbul](https://istanbul.js.org/) and [Coveralls](https://coveralls.io) - _so you know your weak spots._
 - Generated [Swagger](https://swagger.io/) documentation for the endpoints, which works well with [SwaggerHub](https://app.swaggerhub.com) - _the expected description of your API._
 - Multiple layers in the code to separate concerns and independently test them - _avoid monolith and complexity._
+- Health check endpoints - _to quickly test your service._
 - Dependency checks with [David](https://david-dm.org/) and [BitHound](https://www.bithound.io/) - _because the majority of your app is not your code._
 - Sample CRUD implementation (in progress) - _to see it all in action_.
 
@@ -119,6 +120,10 @@ The `src/swagger` folder contains the `/swagger.json` endpoint which exports the
 
 You can also reference the `swagger.json` URL when you publish your documentation via [SwaggerHub](https://app.swaggerhub.com), as you can see on the SwaggerHub page of this sample: https://app.swaggerhub.com/apis/balassy/serverless-sample.
 
+### Health check endpoints
+
+The `/health/check` and the `/health/check/detailed` endpoints in the `src/health` folder are provided to run quick checks on your API after deployment.
+
 ## Developer tasks
 
 ### Test the service locally
@@ -169,6 +174,8 @@ Verify that the deployment is completed successfully by opening the URL displaye
 https://<your_custom_domain_name>/api/swagger.json
 ```
 
+Note that this endpoint always downloads the Swagger documentation from the live, published API, even if the code is running locally!
+
 If you don't want to deploy your code, just want to peek into the deployment package, you can run:
 
 ```bash

serverless.yml

@@ -42,6 +42,48 @@ functions:
           method: get
           cors: true
 
+  getHealthCheck:
+    handler: src/health/health.getHealthCheck
+    description: Returns the result of a quick health check of the API.
+
+    events:
+      - http:
+          path: health/check
+          method: get
+          cors: true
+          documentation:
+            summary: Returns the result of a quick health check of the API.
+            tags:
+              - Health
+            description: Returns the result of a quick health check of the API.
+            methodResponses:
+              - statusCode: '200'
+                description: Returned when the operation is completed successfully.
+                responseModels:
+                  "application/json": GetHealthCheck
+              - ${file(./swagger/error-responses/internal-server-error.yml)}
+
+  getHealthCheckDetailed:
+    handler: src/health/health.getHealthCheckDetailed
+    description: Returns the result of a detailed health check of the API.
+
+    events:
+      - http:
+          path: health/detailed
+          method: get
+          cors: true
+          documentation:
+            summary: Returns the result of a detailed health check of the API.
+            tags:
+              - Health
+            description: Returns the result of a detailed health check of the API.
+            methodResponses:
+              - statusCode: '200'
+                description: Returned when the operation is completed successfully.
+                responseModels:
+                  "application/json": GetHealthCheckDetailed
+              - ${file(./swagger/error-responses/internal-server-error.yml)}
+
   getCity:
     handler: src/cities/cities.getCity
     description: Returns a single city.

src/health/health.controller.spec.ts

@@ -0,0 +1,84 @@
+import { expect } from 'chai';
+import { Chance } from 'chance';
+
+import { ApiContext, ApiEvent, ApiHandler, ApiResponse } from '../../shared/api.interfaces';
+import { HttpStatusCode } from '../../shared/http-status-codes';
+import { callSuccess } from '../../test';
+import { ApiResponseParsed } from '../../test/test.interfaces';
+import { HealthController } from './health.controller';
+import { GetHealthCheckDetailedResult, GetHealthCheckResult } from './health.interfaces';
+
+const chance: Chance.Chance = new Chance();
+
+describe('HealthController', () => {
+  let controller: HealthController;
+
+  beforeEach(() => {
+    controller = new HealthController();
+  });
+
+  describe('getHealthCheck function', () => {
+    it('should return HTTP 200 OK', async () => {
+      const response: ApiResponseParsed<GetHealthCheckResult> = await callSuccess<GetHealthCheckResult>(controller.getHealthCheck);
+      expect(response.statusCode).to.equal(HttpStatusCode.Ok);
+    });
+
+    it('should return success', async () => {
+      const response: ApiResponseParsed<GetHealthCheckResult> = await callSuccess<GetHealthCheckResult>(controller.getHealthCheck);
+      expect(response.parsedBody.success).to.equal(true);
+    });
+  });
+
+  describe('getHealthCheckDetailed function', () => {
+    let testData: {
+      requestId: string;
+    };
+
+    beforeEach(() => {
+      testData = {
+        requestId: chance.word()
+      };
+    });
+
+    it('should return HTTP 200 OK', async () => {
+      const response: ApiResponseParsed<GetHealthCheckDetailedResult> = await callSuccessDetailed(controller.getHealthCheckDetailed, testData.requestId);
+      expect(response.statusCode).to.equal(HttpStatusCode.Ok);
+    });
+
+    it('should return success', async () => {
+      const response: ApiResponseParsed<GetHealthCheckDetailedResult> = await callSuccessDetailed(controller.getHealthCheckDetailed, testData.requestId);
+      expect(response.parsedBody.success).to.equal(true);
+    });
+
+    it('should return the request ID', async () => {
+      const response: ApiResponseParsed<GetHealthCheckDetailedResult> = await callSuccessDetailed(controller.getHealthCheckDetailed, testData.requestId);
+      expect(response.parsedBody.requestId).to.equal(testData.requestId);
+    });
+
+    // tslint:disable-next-line arrow-return-shorthand (Long function body.)
+    function callSuccessDetailed(handler: ApiHandler, requestId?: string): Promise<ApiResponseParsed<GetHealthCheckDetailedResult>> {
+      // tslint:disable-next-line typedef (Well-known constructor.)
+      return new Promise((resolve, reject) => {
+        let event: ApiEvent = <ApiEvent> {};
+        if (requestId) {
+          event = <ApiEvent> {
+            requestContext: {
+              requestId
+            }
+          };
+        }
+
+        handler(event, <ApiContext> {}, (error?: Error, result?: ApiResponse): void => {
+          if (typeof result === 'undefined') {
+            reject('No result was returned by the handler!');
+            return;
+          }
+
+          const parsedResult: ApiResponseParsed<GetHealthCheckDetailedResult> = result as ApiResponseParsed<GetHealthCheckDetailedResult>;
+          parsedResult.parsedBody = JSON.parse(result.body) as GetHealthCheckDetailedResult;
+          resolve(parsedResult);
+        });
+      });
+    }
+  });
+});

src/health/health.controller.ts

@@ -0,0 +1,22 @@
+import { ApiCallback, ApiContext, ApiEvent, ApiHandler } from '../../shared/api.interfaces';
+import { ResponseBuilder } from '../../shared/response-builder';
+import { GetHealthCheckDetailedResult, GetHealthCheckResult } from './health.interfaces';
+
+export class HealthController {
+  public getHealthCheck: ApiHandler = (event: ApiEvent, context: ApiContext, callback: ApiCallback): void => {
+    const result: GetHealthCheckResult = {
+      success: true
+    };
+
+    ResponseBuilder.ok<GetHealthCheckResult>(result, callback);
+  }
+
+  public getHealthCheckDetailed: ApiHandler = (event: ApiEvent, context: ApiContext, callback: ApiCallback): void => {
+    const result: GetHealthCheckDetailedResult = {
+      requestId: event.requestContext.requestId,
+      success: true
+    };
+
+    ResponseBuilder.ok<GetHealthCheckDetailedResult>(result, callback);
+  }
+}

src/health/health.interfaces.ts

@@ -0,0 +1,8 @@
+export interface GetHealthCheckResult {
+  success: boolean;
+}
+
+export interface GetHealthCheckDetailedResult {
+  requestId: string;
+  success: boolean;
+}

src/health/health.ts

@@ -0,0 +1,7 @@
+import { ApiHandler } from '../../shared/api.interfaces';
+import { HealthController } from './health.controller';
+
+const controller: HealthController = new HealthController();
+
+export const getHealthCheck: ApiHandler = controller.getHealthCheck;
+export const getHealthCheckDetailed: ApiHandler = controller.getHealthCheckDetailed;

src/health/swagger/get-health-check-detailed.yml

@@ -0,0 +1,11 @@
+name: GetHealthCheckDetailed
+contentType: "application/json"
+schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+      description: Returns true if the health check has found everything all right on the server.
+    requestId:
+      type: string
+      description: Returns the unique identifier of the incoming HTTP request.

src/health/swagger/get-health-check.yml

@@ -0,0 +1,8 @@
+name: GetHealthCheck
+contentType: "application/json"
+schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+      description: Returns true if the health check has found everything all right on the server.

swagger/documentation.yml

@@ -12,6 +12,10 @@ api:
   tags:
     - name: City
       description: Manipulate cities.
+    - name: Health
+      description: Health check.
 models:
   - ${file(./swagger/error-responses/error-response.yml)}
-  - ${file(./src/cities/swagger/get-city-response.yml)}
+  - ${file(./src/cities/swagger/get-city-response.yml)}
+  - ${file(./src/health/swagger/get-health-check.yml)}
+  - ${file(./src/health/swagger/get-health-check-detailed.yml)}