Building the services

Owned by Michel El Hajj (Unlicensed)
Last updated: Jun 23, 2017

Objectives

  1. Get more familiar with the built in Swagger Editor to build a service
  2. Get more familiar with writing BL based on the composer



Scenario

  1. Create petstore Service
    1. Write your APIs documentation
    2. Fill the configuration
    3. Build the service
    4. APIs
  2. Create orders Service
    1. Write your APIs documentation
    2. Fill the configuration
    3. Build the service
    4. APIs & BL explanation
  3. Composer roleĀ 



1. Create petstore ServiceĀ 

To create any service, you need to write your APIs, your service configuration and finally each API business logic based on your needs.

a. Write your APIs documentationĀ 

  • Go to the Develop pillarĀ ā†’ Swagger EditorĀ ā†’ Swagger Documentation Tab
  • Write your APIs documentation and press run to make sure you don't have any error (you can useĀ http://editor.swagger.io/Ā to spot errors then copy the code and paste it in the editor).Ā You can find the codeĀ here.
  • AT this stage, your service isn't yet deployed so you can just try your code to make sure that your schema is correct and as intended. Press on an API, enter the values and press on Try it Out!

b. Fill the configurationĀ 

  • Press on Service Information tab to fill the configuration
  • Fill all the fields with the following inputs:
    • Service Name: petstore
    • Service Group: petstore
    • Service Port: 4215
    • Service Version: 1
    • Request Timeout: 30
    • Request Timeout Renewal: 5
    • extKeyRequired: true
    • oauth: true
    • Session: true
    • Database:
      • Prefix:Ā 
      • Name: petStore
      • multitenant: false
      • model: mongo
  • Click on Generate Service,Ā a zip file will be downloaded

c. Build the serviceĀ 

To learn how to build your service, click here.

d. APIsĀ 

This service contains 4 APIs:

RouteMethodParametersDescription
/petsGETnoneThis API lists all the pets available in the store without any condition, by hitting the pets collection to get its entries.

/pet

POST

pet: {

  • breed: required
  • name: required
  • age: required
  • color: optional
  • quantity: required
  • price: required
  • photoUrls: required
  • description: optional
    }
This API adds a new pet to the store, by inserting a new entry to the database

/pet/:id

PUT

pet: {

  • breed: required
  • name: required
  • age: required
  • color: optional
  • quantity: required
  • price: required
  • photoUrls: required
  • description: optional
    }

id: required

This API updates a pet in the store using the mongo id of the record
/pet/:idDELETEid: requiredThis API deletes a pet from the store using the mongo id record

As we mentioned in the service information 1.b, extKeyRequired is set to true. So, an external key is required and sent in the headers to check if you are logged in and have access to this API.

You can get the code from here.



2. Create orders ServiceĀ 

To create any service, you need to write your APIs, your service configuration and finally each API business logic based on your needs.

a. Write your APIs documentationĀ 

  • Go to theĀ DevelopĀ pillarĀ ā†’Ā Swagger EditorĀ ā†’Ā Swagger DocumentationĀ Tab
  • Write your APIs documentation and press run to make sure you don't have any error (you can useĀ http://editor.swagger.io/Ā to spot errors then copy the code and paste it in the editor). You can find the code here.
  • AT this stage, your service isn't yet deployed so you can just try your code to make sure that your schema is correct and as intended. Press on an API, enter the values and press onĀ Try it Out!

b. Fill the configurationĀ 

  • Press onĀ Service InformationĀ tab to fill the configuration
  • Fill all the fields with the following inputs:
    • Service Name: orders
    • Service Group: orders
    • Service Port: 5216
    • Service Version: 1
    • Request Timeout: 30
    • Request Timeout Renewal: 5
    • extKeyRequired: true
    • oauth: true
    • Session: true
    • urac: true
    • urac_Profile: true
    • Database:
      • Prefix:Ā 
      • Name: orders
      • multitenant: false
      • model: mongo
      • Prefix:Ā 
      • Name: petStore
      • multitenant: false
      • model: mongo
  • Click onĀ Generate Service,Ā a zip file will be downloaded

c. Build the serviceĀ 

To learn how to build your service, clickĀ here.

d. APIs & BL explanationĀ 

This service contains 9 APIs:

RouteMethodParametersDescriptionBL Explanation
/admin/ordersGET
  • start: optional
  • limit: optional
This API lists all the orders made by the users, so the admin can manage them by confirming or rejecting each orderThis API hits the orders collection to count its entries. If the count is >0, it proceeds to get the records and return them with the total number. The total number will be used for the pagination alongside the start and limit parameters
/ordersGET
  • userId: optional
This API lists all orders made by a logged in user, so he can check his previous ordersThis API checks if the user id of the current session has the same id of the urac object then returns this user orders only
/cartGET
  • userId: optional
This API lists all pets added by a user to an anonymous cart or a user cart. An anonymous cart is created if you are not logged in.This API checks if there is a urac object, in other terms if someone is logged in. In case no urac object found, it checks for any records in the session and returns them with their count. The count is used to show the user that the cart isn't empty. In case of urac object, checks if the user id of the current session has the same id of the urac object then returns this user cart only
/mergeCartGET
  • userId: optional
This API merges an anonymous cart saved in the session to the user who's logging inThis API checks for items in the session, in case of no items found it won't change anything. Else, it checks if the user id of the current session has the same id of the urac object. If they match, it checks if the user has items in his cart, if not it will enter all the records directly, else it checks if there is a common item so it will just modify the quantity ordered.

/cart

POST
  • userId: optional
  • petId: required
  • pet: required
This API adds a pet to an anonymous or logged in user cartThis API checks if the user is logged in or not. If not, it adds the pet to the session object after checking if the pet doesn't exists in the cart, or it modifies the quantity ordered in case the pet exists. If the user is logged in, it checks if the user id of the current session has the same id of the urac object then it adds the pet to the orders collection after checking if the pet doesn't exists in the cart, or it modifies the quantity ordered in case the pet exists

/cart/checkout/:id

POST

  • userId: optional
  • id: required
  • petId: required
  • quantity: required
  • infos: required
This API checks out all items in the cart for the logged in user, in case the user is logged in, he will be redirected to the login pageThis API checks if there is a urac object, in other terms if someone is logged in then it checks if the user id of the current session has the same id of the urac object. If so, the quantity ordered of each item will get reduced from the pets collection using the petId and it adds the user infos to each record in the orders collection related to the logged in user
/order/:idPOST
  • id: required
  • pickupDate: required
This API confirms an order by changing it status to ready and adding a pickup date to the recordThis API will update the pet status from pending to ready, add a pickup date to the record and finally send a mail to the client pointing that the order is confirmed with the pickup date from the store
/cart/:idDELETE
  • id: required
  • userId: optional
This API deletes a pet from an anonymous or logged in user cartThis API checks if the user is logged in. If not, it will check the session and delete the item from the cart. Else, it checks if the user id of the current session has the same id of the urac object then deletes the item from the user cart
/order/:idDELETE
  • id: required
  • petId: required
This API rejects an order of a clientThis API gets the record of the rejected order then using the petId found in the record, it increments the quantity in stock by the quantity ordered in the pets collection. AT the end, it sends an email to the client saying that the order has been rejected

As we mentioned in the service information 1.b, extKeyRequired is set to true. So, an external key is required and sent in the headers to check if you are logged in and have access to this API.

You can get the code fromĀ here.



3. Composer roleĀ 

The composer is a ready-made SOAJS component helped us cut time and effort with the following:

  • Initialisation of the database connectivity
  • Standardisation of the response
  • Minimisation of the index.js file
  • Files orchestration with the help of the middlewares

To learn more about the composer, click here.