new PUT endpoints & metadata endpoints removed

Author: Sande3p

docs/skills-api.postman_collection.json

@@ -30,12 +30,8 @@ basePath: "/api/1.0"
 tags:
   - name: "Skills"
     description: "Skills registered in the system"
-  - name: "Skill Metadata"
-    description: "Metadata for Skills registered in the system"
   - name: "Taxonomies"
     description: "Taxonomies registered in the system"
-  - name: "Taxonomy Metadata"
-    description: "Metadata for Taxonomies registered in the system"
 schemes:
   - "https"
 consumes:
@@ -285,16 +281,16 @@ paths:
       tags:
         - "Skills"
       description: >
-        Update an existing skill with given id.
+        Partically update an existing skill with given id.
 
 
         **PERMISSION**
 
         1. permission `UPDATE_SKILL` is required to perform this operation
 
-        2. permission `ADD_SKILL_METADATA` is required if any metadata field is provided.
+        2. permission `ADD_SKILL_METADATA` is required if any new metadata field is provided.
 
-        3. permission `DELETE_SKILL_METADATA` is required if there is any existing metadata field in the skill.
+        3. permission `UPDATE_SKILL_METADATA` is required if any metadata field provided already exist in the skill.
       operationId: "skillsSkillIdPATCH"
       parameters:
         - name: "skillId"
@@ -329,105 +325,21 @@ paths:
         - Bearer: []
       x-swagger-router-controller: "Skills"
 
-  /skills/{skillId}/metadata:
     put:
       tags:
-        - "Skill Metadata"
-      description: >
-        Fully update the metadata of an existing skill with given id.
-
-        Used to entirely overwrite existing metadata.
-
-
-        **PERMISSION**
-
-        1. permission `ADD_SKILL_METADATA` is required if any metadata field is provided.
-
-        2. permission `DELETE_SKILL_METADATA` is required if there is any existing metadata field in the skill.
-      parameters:
-        - name: "skillId"
-          in: "path"
-          description: "The skill id"
-          required: true
-          type: "string"
-          format: "UUID"
-        - in: "body"
-          name: "body"
-          required: true
-          schema:
-            $ref: "#/definitions/SkillMetadataUpdateRequestBody"
-      responses:
-        "200":
-          description: "OK - the request was successful"
-          schema:
-            $ref: "#/definitions/Skill"
-        "400":
-          $ref: "#/definitions/BadRequest"
-        "401":
-          $ref: "#/definitions/Unauthorized"
-        "403":
-          $ref: "#/definitions/Forbidden"
-        "404":
-          $ref: "#/definitions/NotFound"
-        "500":
-          $ref: "#/definitions/ServerError"
-      security:
-        - Bearer: []
-    patch:
-      tags:
-        - "Skill Metadata"
+        - "Skills"
       description: >
-        Partically update the metadata of an existing skill with given id.
-
-        Used to update existing fields in metadata and to add new fields to metadata.
+        Fully update an existing skill with given id.
 
 
         **PERMISSION**
 
-        1. permission `ADD_SKILL_METADATA` is required if any new metadata field is provided.
-
-        2. permission `UPDATE_SKILL_METADATA` is required if any metadata field provided already exist in the skill.
-      parameters:
-        - name: "skillId"
-          in: "path"
-          description: "The skill id"
-          required: true
-          type: "string"
-          format: "UUID"
-        - in: "body"
-          name: "body"
-          required: true
-          schema:
-            $ref: "#/definitions/SkillMetadataUpdateRequestBody"
-      responses:
-        "200":
-          description: "OK - the request was successful"
-          schema:
-            $ref: "#/definitions/Skill"
-        "400":
-          $ref: "#/definitions/BadRequest"
-        "401":
-          $ref: "#/definitions/Unauthorized"
-        "403":
-          $ref: "#/definitions/Forbidden"
-        "404":
-          $ref: "#/definitions/NotFound"
-        "500":
-          $ref: "#/definitions/ServerError"
-      security:
-        - Bearer: []
-    delete:
-      tags:
-        - "Skill Metadata"
-      description: >
-        Remove fields from the metadata of an existing skill with given id.
-
-        404 error will be raised if one or more of the provided fields is missing in the existing metadata.
-
+        1. permission `UPDATE_SKILL` is required to perform this operation
 
-        **PERMISSION**
+        2. permission `ADD_SKILL_METADATA` is required if new metadata fields are provided.
 
-        Permission `DELETE_SKILL_METADATA` is required to perform this operation.
+        3. permission `DELETE_SKILL_METADATA` is required if there is any existing metadata field in the skill.
+      operationId: "skillsSkillIdPUT"
       parameters:
         - name: "skillId"
           in: "path"
@@ -439,7 +351,7 @@ paths:
           name: "body"
           required: true
           schema:
-            $ref: "#/definitions/SkillMetadataDeleteRequestBody"
+            $ref: "#/definitions/SkillRequestBody"
       responses:
         "200":
           description: "OK - the request was successful"
@@ -453,10 +365,13 @@ paths:
           $ref: "#/definitions/Forbidden"
         "404":
           $ref: "#/definitions/NotFound"
+        "409":
+          $ref: "#/definitions/Conflict"
         "500":
           $ref: "#/definitions/ServerError"
       security:
         - Bearer: []
+      x-swagger-router-controller: "Skills"
 
   /taxonomies:
     get:
@@ -674,16 +589,16 @@ paths:
       tags:
         - "Taxonomies"
       description: >
-        Update an existing taxonomy with given id.
+        Partically update an existing taxonomy with given id.
 
 
         **PERMISSION**
 
         1. permission `UPDATE_TAXONOMY` is required to perform this operation
 
-        2. permission `ADD_TAXONOMY_METADATA` is required if any metadata field is provided.
+        2. permission `ADD_TAXONOMY_METADATA` is required if any new metadata field is provided.
 
-        3. permission `DELETE_TAXONOMY_METADATA` is required if there is any existing metadata field in the taxonomy.
+        3. permission `UPDATE_TAXONOMY_METADATA` is required if any metadata field provided already exist in the taxonomy.
       operationId: "skillstaxonomiestaxonomyIdPATCH"
       parameters:
         - name: "taxonomyId"
@@ -717,105 +632,21 @@ paths:
       security:
         - Bearer: []
       x-swagger-router-controller: "Taxonomy"
-  /taxonomies/{taxonomyId}/metadata:
     put:
       tags:
-        - "Taxonomy Metadata"
-      description: >
-        Fully update the metadata of an existing taxonomy with given id.
-
-        Used to entirely overwrite existing metadata.
-
-
-        **PERMISSION**
-
-        1. permission `ADD_TAXONOMY_METADATA` is required if any metadata field is provided.
-
-        2. permission `DELETE_TAXONOMY_METADATA` is required if there is any existing metadata field in the taxonomy.
-      parameters:
-        - name: "taxonomyId"
-          in: "path"
-          description: "The taxonomy id"
-          required: true
-          type: "string"
-          format: "UUID"
-        - in: "body"
-          name: "body"
-          required: true
-          schema:
-            $ref: "#/definitions/TaxonomyMetadataUpdateRequestBody"
-      responses:
-        "200":
-          description: "OK - the request was successful"
-          schema:
-            $ref: "#/definitions/Taxonomy"
-        "400":
-          $ref: "#/definitions/BadRequest"
-        "401":
-          $ref: "#/definitions/Unauthorized"
-        "403":
-          $ref: "#/definitions/Forbidden"
-        "404":
-          $ref: "#/definitions/NotFound"
-        "500":
-          $ref: "#/definitions/ServerError"
-      security:
-        - Bearer: []
-    patch:
-      tags:
-        - "Taxonomy Metadata"
+        - "Taxonomies"
       description: >
-        Partically update the metadata of an existing taxonomy with given id.
-
-        Used to update existing fields in metadata and to add new fields to metadata.
+        Fully update an existing taxonomy with given id.
 
 
         **PERMISSION**
 
-        1. permission `ADD_TAXONOMY_METADATA` is required if any new metadata field is provided.
-
-        2. permission `UPDATE_TAXONOMY_METADATA` is required if any metadata field provided already exist in the taxonomy.
-      parameters:
-        - name: "taxonomyId"
-          in: "path"
-          description: "The taxonomy id"
-          required: true
-          type: "string"
-          format: "UUID"
-        - in: "body"
-          name: "body"
-          required: true
-          schema:
-            $ref: "#/definitions/TaxonomyMetadataUpdateRequestBody"
-      responses:
-        "200":
-          description: "OK - the request was successful"
-          schema:
-            $ref: "#/definitions/Taxonomy"
-        "400":
-          $ref: "#/definitions/BadRequest"
-        "401":
-          $ref: "#/definitions/Unauthorized"
-        "403":
-          $ref: "#/definitions/Forbidden"
-        "404":
-          $ref: "#/definitions/NotFound"
-        "500":
-          $ref: "#/definitions/ServerError"
-      security:
-        - Bearer: []
-    delete:
-      tags:
-        - "Taxonomy Metadata"
-      description: >
-        Remove fields from the metadata of an existing taxonomy with given id.
-
-        404 error will be raised if one or more of the provided fields is missing in the existing metadata.
-
+        1. permission `UPDATE_TAXONOMY` is required to perform this operation
 
-        **PERMISSION**
+        2. permission `ADD_TAXONOMY_METADATA` is required if any metadata field is provided.
 
-        Permission `DELETE_TAXONOMY_METADATA` is required to perform this operation.
+        3. permission `DELETE_TAXONOMY_METADATA` is required if there is any existing metadata field in the taxonomy.
+      operationId: "skillstaxonomiestaxonomyIdPUT"
       parameters:
         - name: "taxonomyId"
           in: "path"
@@ -827,7 +658,7 @@ paths:
           name: "body"
           required: true
           schema:
-            $ref: "#/definitions/TaxonomyMetadataDeleteRequestBody"
+            $ref: "#/definitions/TaxonomyRequestBody"
       responses:
         "200":
           description: "OK - the request was successful"
@@ -841,10 +672,13 @@ paths:
           $ref: "#/definitions/Forbidden"
         "404":
           $ref: "#/definitions/NotFound"
+        "409":
+          $ref: "#/definitions/Conflict"
         "500":
           $ref: "#/definitions/ServerError"
       security:
         - Bearer: []
+      x-swagger-router-controller: "Taxonomy"
 
 securityDefinitions:
   Bearer:
@@ -954,26 +788,6 @@ definitions:
       metadata:
         challengeProminence: "challengeProminence"
         memberProminence: "memberProminence"
-  SkillMetadataUpdateRequestBody:
-    type: "object"
-    description: "The metadata for a skill. Can contain arbitrary fields"
-    properties:
-      challengeProminence:
-        type: "string"
-        description: "The challenge prominence ranging from [0, 1]"
-      memberProminence:
-        type: "string"
-        description: "The member prominence ranging from [0, 1]"
-    example:
-      verions: "1.0.0"
-      random_field: "random_value"
-  SkillMetadataDeleteRequestBody:
-    type: "array"
-    description: "The list of fields to be removed from the metadata for a skill."
-    items:
-      type: string
-      description: "field name"
-    example: ["version", "random_field"]
   Taxonomy:
     allOf:
       - type: "object"
@@ -1015,19 +829,8 @@ definitions:
         description: "The metadata of the taxonomy."
     example:
       name: "name"
-  TaxonomyMetadataUpdateRequestBody:
-    type: "object"
-    description: "The metadata for a taxonomy. Can contain arbitrary fields"
-    example:
-      verions: "1.0.0"
-      random_field: "random_value"
-  TaxonomyMetadataDeleteRequestBody:
-    type: "array"
-    description: "The list of fields to be removed from the metadata for a taxonomy."
-    items:
-      type: string
-      description: "field name"
-    example: ["version", "random_field"]
+      metadata:
+        random_field_name_01: random_value_01
   Unauthorized:
     type: "object"
     properties:

docs/swagger.yaml

@@ -24,6 +24,15 @@ function getControllerMethods (service) {
     res.json(await service.patch(req.params.id, req.body, req.authUser))
   }
 
+  /**
+   * fully update entity by id
+   * @param req the http request
+   * @param res the http response
+   */
+  async function fullyUpdate (req, res) {
+    res.json(await service.fullyUpdate(req.params.id, req.body, req.authUser))
+  }
+
   /**
    * get entity by id
    * @param req the http request
@@ -59,7 +68,8 @@ function getControllerMethods (service) {
     search,
     remove,
     get,
-    patch
+    patch,
+    fullyUpdate
   }
 }
 

src/common/controller-helper.js

@@ -49,15 +49,9 @@ const API_ACTION = {
   SkillCreate: 'skill.create',
   SkillUpdate: 'skill.update',
   SkillDelete: 'skill.delete',
-  SkillPutMetadata: 'skill.putMetadata',
-  SkillPatchMetadata: 'skill.patchMetadata',
-  SkillDeleteMetadata: 'skill.deleteMetadata',
   TaxonomyCreate: 'taxonomy.create',
   TaxonomyUpdate: 'taxonomy.update',
-  TaxonomyDelete: 'taxonomy.delete',
-  TaxonomyPutMetadata: 'taxonomy.putMetadata',
-  TaxonomyPatchMetadata: 'taxonomy.patchMetadata',
-  TaxonomyDeleteMetadata: 'taxonomy.deleteMetadata'
+  TaxonomyDelete: 'taxonomy.delete'
 }
 
 module.exports = {

src/constants.js

@@ -30,6 +30,11 @@ module.exports = {
       auth: 'jwt',
       permission: 'skill.edit'
     },
+    put: {
+      method: Controller.fullyUpdate,
+      auth: 'jwt',
+      permission: 'skill.edit'
+    },
     delete: {
       method: Controller.remove,
       auth: 'jwt',

src/modules/SkillMetadata/controller.js

@@ -69,46 +69,25 @@ create.schema = {
 }
 
 /**
- * patch skill by id
- * @param id the skill id
- * @param entity the request skill entity
+ * Update skill by id. Used in functions patch and fullyUpdate.
+ *
+ * @param instance the skill instance
+ * @param updateData the data to be updated
  * @param auth the auth object
  * @return the updated skill
  */
-async function patch (id, entity, auth) {
-  let taxonomy
-  if (entity.taxonomyId) {
-    taxonomy = await dbHelper.get(Taxonomy, entity.taxonomyId)
-  }
-
-  await dbHelper.makeSureUnique(Skill, entity, uniqueFields)
-
-  const instance = await dbHelper.get(Skill, id)
-
-  if (entity.metadata) {
-    if (Object.keys(entity.metadata).length) {
-      // check permission for adding new metadata fields
-      serviceHelper.hasPermission(PERMISSION.ADD_SKILL_METADATA, auth)
-    }
-    if (Object.keys(instance.metadata).length) {
-      // check permission for removing existing metadata fields
-      serviceHelper.hasPermission(PERMISSION.DELETE_SKILL_METADATA, auth)
-    }
-  }
-
+async function update (instance, updateData, auth) {
   let payload
   try {
     return await sequelize.transaction(async () => {
       const newEntity = await instance.update({
-        ...entity,
+        ...updateData,
         updatedBy: helper.getAuthUser(auth)
       })
 
       payload = newEntity.dataValues
 
-      if (!taxonomy) {
-        taxonomy = await dbHelper.get(Taxonomy, newEntity.taxonomyId)
-      }
+      const taxonomy = await dbHelper.get(Taxonomy, newEntity.taxonomyId)
       const updated = { ...newEntity.dataValues, taxonomyName: taxonomy.name }
 
       await serviceHelper.patchRecordInEs(resource, updated)
@@ -123,6 +102,47 @@ async function patch (id, entity, auth) {
   }
 }
 
+/**
+ * Patch skill by id.
+ * If the metadata field is provided, existing metadata fields would be updated and new metadata fields would be added.
+ *
+ * @param id the skill id
+ * @param entity the request skill entity
+ * @param auth the auth object
+ * @return the updated skill
+ */
+async function patch (id, entity, auth) {
+  // check if the skill exists or not
+  const instance = await dbHelper.get(Skill, id)
+
+  if (entity.taxonomyId && entity.taxonomyId !== instance.taxonomyId) {
+    // check if the taxonomy exists or not
+    await dbHelper.get(Taxonomy, entity.taxonomyId)
+  }
+
+  // check if the skill has conflict or not
+  await dbHelper.makeSureUnique(Skill, entity, uniqueFields)
+
+  if (entity.metadata) {
+    const inputFields = Object.keys(entity.metadata)
+    const existingFields = Object.keys(instance.metadata)
+    const sharedFields = _.intersection(inputFields, existingFields)
+
+    if (inputFields.length > sharedFields.length) {
+      // check permission for adding new fields
+      serviceHelper.hasPermission(PERMISSION.ADD_SKILL_METADATA, auth)
+    }
+    if (sharedFields.length) {
+      // check permission for updating fields
+      serviceHelper.hasPermission(PERMISSION.UPDATE_SKILL_METADATA, auth)
+    }
+  }
+
+  const updateData = { ...instance, ...entity, metadata: { ...instance.metadata, ...entity.metadata } }
+
+  return update(instance, updateData, auth)
+}
+
 patch.schema = {
   id: joi.string().uuid().required(),
   entity: joi.object().keys({
@@ -138,6 +158,56 @@ patch.schema = {
   auth: joi.object()
 }
 
+/**
+ * Fully update skill by id.
+ * Existing metadata fields would be entirely replace with the new ones.
+ *
+ * @param id the skill id
+ * @param entity the request skill entity
+ * @param auth the auth object
+ * @return the updated skill
+ */
+async function fullyUpdate (id, entity, auth) {
+  // check if the skill exists or not
+  const instance = await dbHelper.get(Skill, id)
+
+  if (entity.taxonomyId !== instance.taxonomyId) {
+    // check if the taxonomy exists or not
+    await dbHelper.get(Taxonomy, entity.taxonomyId)
+  }
+
+  // check if the skill has conflict or not
+  await dbHelper.makeSureUnique(Skill, entity, uniqueFields)
+
+  if (Object.keys(entity.metadata).length) {
+    // check permission for adding new metadata fields
+    serviceHelper.hasPermission(PERMISSION.ADD_SKILL_METADATA, auth)
+  }
+  if (Object.keys(instance.metadata).length) {
+    // check permission for removing existing metadata fields
+    serviceHelper.hasPermission(PERMISSION.DELETE_SKILL_METADATA, auth)
+  }
+
+  const updateData = entity
+
+  return update(instance, updateData, auth)
+}
+
+fullyUpdate.schema = {
+  id: joi.string().uuid().required(),
+  entity: joi.object().keys({
+    taxonomyId: joi.string().uuid().required(),
+    name: joi.string().required(),
+    uri: joi.string().default(null),
+    externalId: joi.string().default(null),
+    metadata: joi.object().keys({
+      challengeProminence: joi.prominence('challengeProminence'),
+      memberProminence: joi.prominence('memberProminence')
+    }).unknown(true).required()
+  }).required(),
+  auth: joi.object()
+}
+
 /**
  * get skill by id
  * @param id the skill id
@@ -263,6 +333,7 @@ module.exports = {
   create,
   search,
   patch,
+  fullyUpdate,
   get,
   remove
 }

src/modules/SkillMetadata/route.js

@@ -30,6 +30,11 @@ module.exports = {
       auth: 'jwt',
       permission: 'taxonomy.edit'
     },
+    put: {
+      method: Controller.fullyUpdate,
+      auth: 'jwt',
+      permission: 'taxonomy.edit'
+    },
     delete: {
       method: Controller.remove,
       auth: 'jwt',

src/modules/SkillMetadata/service.js

@@ -57,37 +57,26 @@ create.schema = {
 }
 
 /**
- * patch taxonomy by id
- * @param id the taxonomy id
- * @param entity the request taxonomy entity
+ * Update taxonomy by id. Used in functions patch and fullyUpdate.
+ *
+ * @param instance the taxonomy instance
+ * @param updateData the data to be updated
  * @param auth the auth object
- * @param params the query params
  * @return the updated taxonomy
  */
-async function patch (id, entity, auth) {
-  const instance = await dbHelper.get(Taxonomy, id)
-
-  if (entity.metadata) {
-    if (Object.keys(entity.metadata).length) {
-      // check permission for adding new metadata fields
-      serviceHelper.hasPermission(PERMISSION.ADD_TAXONOMY_METADATA, auth)
-    }
-    if (Object.keys(instance.metadata).length) {
-      // check permission for removing existing metadata fields
-      serviceHelper.hasPermission(PERMISSION.DELETE_TAXONOMY_METADATA, auth)
-    }
-  }
-
+async function update (instance, updateData, auth) {
   let payload
   try {
     return await sequelize.transaction(async () => {
       const newEntity = await instance.update({
-        ...entity,
+        ...updateData,
         updatedBy: helper.getAuthUser(auth)
       })
+
       payload = newEntity.dataValues
 
       await serviceHelper.patchRecordInEs(resource, newEntity.dataValues)
+
       return helper.omitAuditFields(newEntity.dataValues)
     })
   } catch (e) {
@@ -98,6 +87,39 @@ async function patch (id, entity, auth) {
   }
 }
 
+/**
+ * Patch taxonomy by id.
+ * If the metadata field is provided, existing metadata fields would be updated and new metadata fields would be added.
+ *
+ * @param id the taxonomy id
+ * @param entity the request taxonomy entity
+ * @param auth the auth object
+ * @param params the query params
+ * @return the updated taxonomy
+ */
+async function patch (id, entity, auth) {
+  const instance = await dbHelper.get(Taxonomy, id)
+
+  if (entity.metadata) {
+    const inputFields = Object.keys(entity.metadata)
+    const existingFields = Object.keys(instance.metadata)
+    const sharedFields = _.intersection(inputFields, existingFields)
+
+    if (inputFields.length > sharedFields.length) {
+      // check permission for adding new fields
+      serviceHelper.hasPermission(PERMISSION.ADD_TAXONOMY_METADATA, auth)
+    }
+    if (sharedFields.length) {
+      // check permission for updating fields
+      serviceHelper.hasPermission(PERMISSION.UPDATE_TAXONOMY_METADATA, auth)
+    }
+  }
+
+  const updateData = { ...instance, ...entity, metadata: { ...instance.metadata, ...entity.metadata } }
+
+  return update(instance, updateData, auth)
+}
+
 patch.schema = {
   id: joi.string().uuid().required(),
   entity: joi.object().keys({
@@ -107,6 +129,44 @@ patch.schema = {
   auth: joi.object()
 }
 
+/**
+ * Fully update taxonomy by id.
+ * Existing metadata fields would be entirely replace with the new ones.
+ *
+ * @param id the taxonomy id
+ * @param entity the request taxonomy entity
+ * @param auth the auth object
+ * @param params the query params
+ * @return the updated taxonomy
+ */
+async function fullyUpdate (id, entity, auth) {
+  const instance = await dbHelper.get(Taxonomy, id)
+
+  if (entity.metadata) {
+    if (Object.keys(entity.metadata).length) {
+      // check permission for adding new metadata fields
+      serviceHelper.hasPermission(PERMISSION.ADD_TAXONOMY_METADATA, auth)
+    }
+    if (Object.keys(instance.metadata).length) {
+      // check permission for removing existing metadata fields
+      serviceHelper.hasPermission(PERMISSION.DELETE_TAXONOMY_METADATA, auth)
+    }
+  }
+
+  const updateData = entity
+
+  return update(instance, updateData, auth)
+}
+
+fullyUpdate.schema = {
+  id: joi.string().uuid().required(),
+  entity: joi.object().keys({
+    name: joi.string().required(),
+    metadata: joi.object().default({})
+  }).required(),
+  auth: joi.object()
+}
+
 /**
  * get taxonomy by id
  * @param id the taxonomy id
@@ -201,6 +261,7 @@ module.exports = {
   create,
   search,
   patch,
+  fullyUpdate,
   get,
   remove
 }