Customer Management API implementation by using Swagger Jersey generated server

SOLUTION REQUIREMENT:

• Design a RESTful API using RAML that contains a single resource, customers, and allows the following:
  • List customers
  • Create a new customer
  • Update a customer
  • Deletes a customer You may constrain the customer object to first name, last name and addresses, and the format to JSON.

USECASE:

1. A consumer may periodically (every 5 minutes) consume the API to enable it (the consumer) to maintain a copy of the provider API's customers (the API represents the system of record)
2. A mobile application used by customer service representatives that uses the API to retrieve and update the customers details
3. Simple extension of the API to support future resources such as orders and products

DESIGN APPROACH:

• Design:>
  • used https://studio.restlet.com studio to define/design API specification
  • customerid field is primary key for Customer Data and defined as auto-increment
  • 3 main implementation services:
    • listCustomers (GET)
      • this is to list all customers
    • addCustomer (POST)
      • this is to add a new customer with Customer json data in Request Body
    • customer: there are further 3 supported operations via HTTP method:
      • get (GET): this is to get customer details by custoemrId
      • update (PUT): this is to update customer details by customerId with Customer json data in Request Body
      • delete (DELETE): this is to delete customer by customerId
• Development:>
  • restlet studio to export to RAML 1.0
  • eclipse for development IDE
  • GIT for source code version control
  • swagger-codegen for Java (JAX-RS) server stubs
  • Jetty server for handling API request/response
  • maven for building and running server environment
  • json-simple library for handing json string
  • mysql server for data storage
  • mysql-connect and JPA (Java Persistence API) libraries for DB connection
• Test:> used Postman for REST API testing:
  • List customers: http://localhost:8080/listCustomers : GET with HTTP return code 200 for successful extraction
    • response body contains Customer data list in either XML or JSON format
  • Create new customer: http://localhost:8080/addCustomer : POST with HTTP return code 201 for successful insertion
  • Update customer: http://localhost:8080/customer/{customerId} : PUT with HTTP return code 200 for successful update
  • Delete customer: http://localhost:8080/customer/{customerId} : DELETE with HTTP return code 204 for successful deletion
  • Get customer: http://localhost:8080/customer/{customerId} : GET with HTTP return code 200 for successful extraction
    • response body contains Customer data list in either XML or JSON format
  • NOTE:
    • HTTP header needs to have the following definition: Content-Type=application/json
    • test script is available @ https://github.com/simhead/customermanagement/blob/master/json/customers.postman_collection.json
• Error Handling:> only basic data handling is implemented at HTTP protocol level (status code with 40X)
  • List customers:
    • 404 if no customers FOUND
  • Create new customer: http://localhost:8080/addCustomer :
    • 415 if there is something wrong with POST body data
  • Update customer: http://localhost:8080/customer/{customerId}:
    • 415 if there is something wrong with PUT body data
  • Delete customer: http://localhost:8080/customer/{customerId}:
    • 404 no customer id found to delete
  • Get customer:
    • 404 if customer id NOT FOUND

GIT location: https://github.com/simhead/customermanagement

Usage Overview

This server was generated by the swagger-codegen project. By using the OpenAPI-Spec from a remote server, you can easily generate a server stub. This is an example of building a swagger-enabled JAX-RS server.

This example uses the JAX-RS framework.

To run the server, please execute the following:

mvn clean package jetty:run

You can then view the swagger listing here:

http://localhost:8080/swagger.json

Deliverables:

• The RAML spec itself
  • DONE - https://github.com/simhead/customermanagement/blob/master/RAML/customer.raml
• Commentary on the interaction of use case 1 with the API
  • first call of http://localhost:8080/listCustomers service takes around 6 sec (this is to create DB connection object) but subsequent calls can use cached DB connection to reduce time significantly, i.e. less than 1 sec. NOTE: in PROD, this can be improved by using DB Connection Pooling. Either way this service can support the requirement of 5 min polling cycle.
  • Consumer can setup a schedule task to consume http://localhost:8080/listCustomers API to get all customers in real time. NOTE: if the list is too big then this may not be a good idea
  • To handle large set of data in near real time, the following can be done:
    • create an API to trigger a batch customer data extraction process and returns JobID # to Consumer.
    • once this extraction is done then server stores in an outbound folder or in a queue and notifies to Consumer.
    • finally Consumer access server's outbound folder or queue to retrieve the Customer data.
• Commentary on interaction of use case 2 with the API
  • As part of Data design, the primary key for Customer Data is "CUSTOMERID" this means that A mobile application used by customer service reps can either:
  1. consume http://localhost:8080/listCustomers API to retrieve all customers and look for "customerid" field value to use it for subsequent call "http://localhost:8080/customer/{customerId}" with PUT method to update Customer data fields
  2. if "customerid" is known then just consume "http://localhost:8080/customer/{customerId}" service with PUT method to update Customer data fields
• Commentary on how the API could be extended for use case 3
  • Proposal to support Products (these are items that Customers can purchase) and Orders (Customer's purchased item(s)):
    • Step 1: Extend Customer table to include field to store purchased item
    • Step 2: Define Product table consists of ProductId, ProductName, ProductDescription, Price, Status, etc.
    • Step 3: Define Order table consists of OrderId, OrderName, PurchaseDate, ActivationDate, Status, customerId (linked to Customer), ProductId (linked to Product), etc.
    • Step 4: APIs to
      • create/update/decommission Product
      • create/update/delete Order
      • Plus more depends on requirement....
• Commentary on any 'interesting' design decisions you made (and alternative options considered)
  • See section "DESIGN APPROACH" for the solution design description
• Link to git repository where the code is stored along with the README.md
  • DONE - https://github.com/simhead/customermanagement/blob/master/README.md

TODO (Future expansion):

• slow db connection due to server being located in remote US - only applicable for first call, subsequent calls are using cached dB connection.
• Products and Orders are defined in the placeholder for future expansion and use customerID for primary key relationship.