suggestgrid 0.1.15.pre.SNAPSHOT

data/spec/swagger.yaml

@@ -0,0 +1,1169 @@
+swagger: '2.0'
+
+info:
+  title: SuggestGrid
+  version: 0.1.15-SNAPSHOT
+  description: SuggestGrid is an recommendation and personalization service.
+  x-codegen-settings:
+    appendContentHeaders: true
+    generateAsyncCode: true
+    useMethodPrefix: false
+    useModelPostfix: false
+    useEnumPostfix: false
+    useConstructorsForConfig: false
+    iOSUseAppInfoPlist: true
+    androidUseAppManifest: true
+    collectParameters: false
+    csharpDefaultNamespace: SuggestGrid
+    javaDefaultPackageName: com.suggestgrid
+    brandLabel: SuggestGrid
+    userAgent: SUGGESTGRID
+    projectName: SuggestGrid
+    enableAdditionalModelProperties: false
+    preserveParameterOrder: true
+
+host: localhost:9090
+
+schemes:
+  - http
+
+securityDefinitions:
+  basicAuth:
+    type: basic
+    description: HTTP Basic Authentication. Works over `HTTP`
+
+security:
+  - basicAuth: []
+
+consumes:
+  - application/json
+
+produces:
+  - application/json
+
+tags:
+  - name: type
+    description: Type Methods
+    x-docs-text: |
+      Type methods are used for managing SuggestGrid types.
+      For more information on types, refer to [Types concept documentation](http://www.suggestgrid.com/docs/concepts#types).
+    x-methods:
+      - create_type
+      - get_type
+      - delete_type
+      - get_all_types
+      - delete_all_types
+  - name: action
+    description: Action Methods
+    x-docs-text: |
+      Action methods are for posting and deleting actions.
+      For more information on actions, refer to [Actions concept documentation](http://www.suggestgrid.com/docs/concepts#actions).
+    x-methods:
+      - post_action
+      - post_bulk_actions
+      - get_actions
+      - delete_actions
+  - name: metadata
+    description: Metadata Methods
+    x-docs-text: |
+      Metadata methods are for posting and deleting metadata.
+      For more information on metadata, refer to [Metadata concept documentation ](http://www.suggestgrid.com/docs/concepts#metadata).
+    x-methods:
+      - post_user
+      - post_bulk_users
+      - get_users
+      - delete_user
+      - delete_all_users
+      - post_item
+      - post_bulk_items
+      - get_items
+      - delete_item
+      - delete_all_items
+  - name: recommendation
+    description: Recommnedation Methods
+    x-docs-text: |
+      Recommnedation methods are for getting recommended items or users responses from SuggestGrid.
+      For more information on recommendations, refer to [Recommendations concept documentation](http://www.suggestgrid.com/docs/concepts#recommendations).
+    x-methods:
+      - get_recommended_users
+      - get_recommended_items
+  - name: similarity
+    description: Similarity Methods
+    x-docs-text: |
+      Similarity methods are for getting similar items or users responses from SuggestGrid.
+      For more information on similars, refer to [Similarities concept documentation](http://www.suggestgrid.com/docs/concepts#similarities).
+    x-methods:
+      - get_similar_users
+      - get_similar_items
+
+definitions:
+  Action:
+    type: object
+    description: An action object.
+    properties:
+      type:
+        type: string
+        description: The type that the action belongs to.
+      user_id:
+        type: string
+        description: The user id of the performer of the action.
+      item_id:
+        type: string
+        description: The item id of the item the action is performed on.
+      rating:
+        type: number
+        description: The optional rating, if the type is explicit.
+    required:
+      - type
+      - user_id
+      - item_id
+  Filter:
+    type: object
+    description: |
+    additionalProperties:
+      type:
+        - string
+        - integer
+        - number
+        - boolean
+  Metadata:
+    type: object
+    description: |
+    properties:
+      id:
+        type: string
+        description: |
+    additionalProperties:
+      type:
+        - string
+        - integer
+        - number
+        - boolean
+    required:
+      - id
+  # Request Bodies
+  TypeRequestBody:
+    type: object
+    description: |
+    properties:
+      rating:
+        type: string
+        description:  |-
+          Could be "explicit" or "implicit"
+          The default is "implicit".
+  GetRecommendedUsersBody:
+    type: object
+    description: |
+    properties:
+      type:
+        type: string
+        description: |
+      types:
+        type: string
+        description: |
+      item_id:
+        type: string
+        description: |
+      item_ids:
+        type: array
+        description: |
+        items:
+          type: string
+      size:
+        type: integer
+        description: |
+      similar_user_id:
+        type: string
+        description: |
+      fields:
+        type: array
+        items:
+          type: string
+        description: |
+      filter:
+        $ref: '#/definitions/Filter'
+      except:
+        type: array
+        items:
+          type: string
+        description: |
+          These ids will not be included in the response.
+  GetRecommendedItemsBody:
+    type: object
+    description: |
+    properties:
+      type:
+        type: string
+        description: |
+      types:
+        type: string
+        description: |
+      user_id:
+        type: string
+        description: |
+      user_ids:
+        type: array
+        description: |
+        items:
+          type: string
+      size:
+        type: integer
+        description: |
+      similar_item_id:
+        type: string
+        description: |
+      fields:
+        type: array
+        items:
+          type: string
+        description: |
+      filter:
+        $ref: '#/definitions/Filter'
+      except:
+        type: array
+        items:
+          type: string
+        description: |
+          These ids will not be included in the response.
+  GetSimilarUsersBody:
+    type: object
+    description: |
+    properties:
+      type:
+        type: string
+        description: |
+      types:
+        type: string
+        description: |
+      user_id:
+        type: string
+        description: |
+      user_ids:
+        type: array
+        description: |
+        items:
+          type: string
+      size:
+        type: integer
+        description: |
+      fields:
+        type: array
+        items:
+          type: string
+        description: |
+      filter:
+        $ref: '#/definitions/Filter'
+      except:
+        type: array
+        items:
+          type: string
+        description: |
+          These ids will not be included in the response.
+  GetSimilarItemsBody:
+    type: object
+    description: |
+    properties:
+      type:
+        type: string
+        description: |
+      types:
+        type: string
+        description: |
+      item_id:
+        type: string
+        description: |
+          Get similar items to given item id. Either item id or item ids must be provided.
+      item_ids:
+        type: array
+        description: |
+          Get similar items to given item ids. Either item id or item ids must be provided.
+        items:
+          type: string
+      size:
+        type: integer
+        description: |
+      fields:
+        type: array
+        items:
+          type: string
+        description: |
+      filter:
+        $ref: '#/definitions/Filter'
+      except:
+        type: array
+        items:
+          type: string
+        description: |
+          These ids will not be included in the response.
+  # Responses
+  MessageResponse:
+    type: object
+    description: |
+    properties:
+      message:
+        type: string
+        description: Message of the response.
+  CountResponse:
+    type: object
+    description: |
+    properties:
+      count:
+        type: integer
+        format: int32
+        description: |
+  ErrorResponse:
+    type: object
+    description: |
+    properties:
+      message:
+        type: string
+        description: Message of the response.
+      status:
+        type: integer
+        format: int32
+        description: Status code of the response. It is not 2XX.
+  GetTypesResponse:
+    type: object
+    description: |
+    properties:
+      types:
+        type: array
+        description: The list of type names
+        items:
+          type: string
+      status:
+        type: integer
+        format: int32
+        description: Status code of the response. It is not 2XX.
+  GetTypeResponse:
+    type: object
+    description: |
+    properties:
+      rating:
+        type: string
+        description: Either 'implicit' or 'explicit'
+  BulkSchemaErrorResponse:
+    type: object
+    description: |
+    properties:
+      message:
+        type: string
+        description: Message of the response.
+      errors:
+        type: array
+        items:
+          $ref: '#/definitions/SchemaErrorResponse'
+  SchemaErrorResponse:
+    type: object
+    description: Error response returned due to Schema validations.
+    properties:
+      message:
+        type: string
+        description: Message of the response.
+      value:
+        type: object
+        description: The cause of the error.
+      error:
+        type: object
+        description: Programatic description of the error.
+  MetadataInformationResponse:
+    type: object
+    description: |
+    properties:
+      count:
+        type: integer
+        format: int64
+        description: The number of users or items with metadata.
+  UsersResponse:
+    type: object
+    description: |
+    properties:
+      count:
+        type: integer
+        format: int64
+        description: The number of users in the response.
+      users:
+        type: array
+        items:
+          $ref: '#/definitions/Metadata'
+  ItemsResponse:
+    type: object
+    description: |
+    properties:
+      count:
+        type: integer
+        format: int64
+        description: The number of items in the response.
+      items:
+        type: array
+        items:
+          $ref: '#/definitions/Metadata'
+
+paths:
+  # Type Paths
+  /v1/types:
+    get:
+      tags:
+        - type
+      operationId: get_all_types
+      summary: Get All Types
+      description: Get all type names in an array named types.
+      responses:
+        200:
+          description: Get types response.
+          schema:
+            $ref: '#/definitions/GetTypesResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+    delete:
+      tags:
+        - type
+      operationId: delete_all_types
+      summary: Delete All Types
+      description: Deletes ALL types and ALL actions.
+      responses:
+        200:
+          description: Get types response.
+          schema:
+            $ref: '#/definitions/GetTypesResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  /v1/types/{type}:
+    get:
+      tags:
+        - type
+      operationId: get_type
+      summary: Get Properties of a Type
+      description: Get the options of a type. Has rating parameter.
+      parameters:
+        - name: type
+          in: path
+          description: The name of the type to get properties.
+          required: true
+          type: string
+          format: id
+      responses:
+        200:
+          description: Get type response.
+          schema:
+            $ref: '#/definitions/GetTypeResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+    put:
+      tags:
+        - type
+      operationId: create_type
+      summary: Create a New Type
+      description: Creates a new implicit or explicit type.
+      parameters:
+        - name: type
+          in: path
+          description: The name of the type to be created.
+          required: true
+          type: string
+          format: id
+        - name: body
+          in: body
+          description: Optional body for the rating parameter.
+          required: false
+          schema:
+            $ref: '#/definitions/TypeRequestBody'
+      responses:
+        200:
+          description: Type is created.
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        402:
+          description: Type limit reached.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        409:
+          description: Type already exists.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        422:
+          description: Rating type is not `implicit` or `explicit`.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+    delete:
+      tags:
+        - type
+      operationId: delete_type
+      summary: Delete a Type
+      description: |
+        Deletes a type with ALL of its actions and recommendation model.
+        Do not use this if you will need the type.
+      parameters:
+        - name: type
+          in: path
+          description: The name of the type to be deleted.
+          required: true
+          type: string
+          format: id
+      responses:
+        200:
+          description: Type is deleted
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        404:
+          description: Type does not exists.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  # Action Paths
+  /v1/actions:
+    post:
+      tags:
+        - action
+      operationId: post_action
+      summary: Post an Action
+      description: |
+        Posts an action to the given type in the body.
+        The body must have user id, item id and type.
+        Rating is required for actions sent to an explicit type.
+      parameters:
+        - name: body
+          in: body
+          description: The action to be posted.
+          required: true
+          schema:
+            $ref: '#/definitions/Action'
+      responses:
+        200:
+          description: Action posted.
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        400:
+          description: Required `user_id` or `item_id` parameters are missing from the request body.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        402:
+          description: Action limit exceeded.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        404:
+          description: Type does not exists.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+    get:
+      tags:
+        - action
+      operationId: get_actions
+      summary: Get Actions
+      description: |
+                   Type must be provided. Additionally,
+
+                   * If both `user_id` and `item_id` are supplied it returns the count of the corresponding actions.
+                   * If only `user_id` is provided, it returns the count of all the action of the given user.
+                   * If only `user_id` is provided, it returns the count of all the action of the given item.
+                   * If only `older_than` is provided, it returns the count of actions older than the given timestamp.
+                   * If a few of these parameters are provided, it returns the count of the intersection of these parameters.
+                   * If none of these are provided, it returns the count of the whole type.
+      parameters:
+        - name: type
+          in: query
+          description: The type of the actions.
+          required: false
+          type: string
+          format: id
+        - name: user_id
+          in: query
+          description: The user id of the actions.
+          required: false
+          type: string
+          format: id
+        - name: item_id
+          in: query
+          description: The item id of the actions.
+          required: false
+          type: string
+          format: id
+        - name: older_than
+          in: query
+          description: |
+                       Delete all actions of a type older than the given timestamp or time.
+                       Valid times are 1s, 1m, 1h, 1d, 1M, 1y, or unix timestamp (like 1443798195).
+          required: false
+          type: string
+          format: id
+      responses:
+        200:
+          description: Successfully deleted actions.
+          schema:
+            $ref: '#/definitions/CountResponse'
+        400:
+          description: Required `user_id` or `item_id` parameters are missing from the request body.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+    delete:
+      tags:
+        - action
+      operationId: delete_actions
+      summary: Delete Actions
+      description: |
+                   Type must be provided. Additionally,
+
+                   * If both user id and item id are supplied the user's actions on the item will be deleted.
+                   * If only user id is provided, all actions of the user will be deleted.
+                   * If only item id is provided, all actions on the item will be deleted.
+                   * If only older than is provided, all actions older than the timestamp or the duration will be deleted.
+                   * If a few of these parameters are provided, delete action will be executed within intersection of these parameters.
+                   * One of these parameters must be provided. In order to delete all actions, delete the type.
+      parameters:
+        - name: type
+          in: query
+          description: The type of the actions.
+          required: false
+          type: string
+          format: id
+        - name: user_id
+          in: query
+          description: The user id of the actions.
+          required: false
+          type: string
+          format: id
+        - name: item_id
+          in: query
+          description: The item id of the actions.
+          required: false
+          type: string
+          format: id
+        - name: older_than
+          in: query
+          description: |
+                       Delete all actions of a type older than the given timestamp or time.
+                       Valid times are 1s, 1m, 1h, 1d, 1M, 1y, or unix timestamp (like 1443798195).
+          required: false
+          type: string
+          format: id
+      responses:
+        200:
+          description: Successfully deleted actions.
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        400:
+          description: Required `user_id` or `item_id` parameters are missing from the request body.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        404:
+          description: Type does not exists.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        422:
+          description: No query parameter (`user_id`, `item_id`, or `older_than`) is given.  In order to delete all actionsdelete the type.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  /v1/actions/_bulk:
+    post:
+      tags:
+        - action
+      operationId: post_bulk_actions
+      summary: Post Bulk Actions
+      description: |
+        Posts bulk actions to SuggestGrid.
+        The recommended method for posting multiple actions at once.
+      consumes:
+       - text/plain; charset=utf-8
+      parameters:
+        - name: body
+          in: body
+          description: |
+            A number of action objects separated with newlines.
+            Note that this is not a valid JSON data structure.
+            The body size is limited to 10 thousand lines.
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Bulk action request executed.
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        402:
+          description: Action limit exceeded.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  # Metadata Paths
+  /v1/users/{user_id}:
+    delete:
+      tags:
+        - metadata
+      operationId: delete_user
+      summary: Delete a User
+      description: Delete a user metadata with the given user_id.
+      parameters:
+        - name: user_id
+          in: path
+          description: The user_id to delete its metadata.
+          required: true
+          type: string
+          format: id
+      responses:
+        200:
+          description: Deleted a user metadata.
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  /v1/users:
+    post:
+        tags:
+          - metadata
+        operationId: post_user
+        summary: Post a User
+        description: Posts a user metadata.
+        parameters:
+          - name: metadata
+            in: body
+            description: The metadata to be saved. Metadata format has its restrictions.
+            required: true
+            schema:
+              $ref: '#/definitions/Metadata'
+        responses:
+          200:
+            description: Posted a user metadata.
+            schema:
+              $ref: '#/definitions/MessageResponse'
+          400:
+            description: Metadata is invalid.
+            schema:
+              $ref: '#/definitions/SchemaErrorResponse'
+          429:
+            description: Too many requests.
+            schema:
+              $ref: '#/definitions/ErrorResponse'
+          default:
+            description: Unexpected internal error.
+            schema:
+              $ref: '#/definitions/ErrorResponse'
+    get:
+      tags:
+        - metadata
+      operationId: get_users
+      summary: Get Users
+      description: Get information about users. Only returns count at the moment.
+      responses:
+        200:
+          description: Information on users.
+          schema:
+            $ref: '#/definitions/MetadataInformationResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+    delete:
+      tags:
+        - metadata
+      operationId: delete_all_users
+      summary: Delete All Users
+      description: Deletes all user metadata from SuggestGrid.
+      responses:
+        200:
+          description: Deleted all user metadata.
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  /v1/items/{item_id}:
+    delete:
+      tags:
+        - metadata
+      operationId: delete_item
+      summary: Delete an Item
+      description: Delete an item metadata with the given item_id.
+      parameters:
+        - name: item_id
+          in: path
+          description: The item_id to delete its metadata.
+          required: true
+          type: string
+          format: id
+      responses:
+        200:
+          description: Deleted an item metadata.
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  /v1/items:
+    post:
+      tags:
+        - metadata
+      operationId: post_item
+      summary: Post an Item
+      description: |
+        Posts an item metadata.
+        This metadata can be used to filter or to be included in recommendations and similars methods.
+      parameters:
+        - name: body
+          in: body
+          description: The metadata to be saved. Metadata format has its restrictions.
+          required: true
+          schema:
+            $ref: '#/definitions/Metadata'
+      responses:
+        200:
+          description: Posted an item metadata.
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        400:
+          description: Metadata is invalid.
+          schema:
+            $ref: '#/definitions/SchemaErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+    get:
+      tags:
+        - metadata
+      operationId: get_items
+      summary: Get Items
+      description: Get information about items. Only returns count at the moment.
+      responses:
+        200:
+          description: Information on items.
+          schema:
+            $ref: '#/definitions/MetadataInformationResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+    delete:
+      tags:
+        - metadata
+      operationId: delete_all_items
+      summary: Delete All Items
+      description: |
+        Delete all items metadata.
+        This method would flush all items metadata on SuggestGrid.
+      responses:
+        200:
+          description: Deleted all item metadata.
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  /v1/users/_bulk:
+    post:
+      tags:
+        - metadata
+      operationId: post_bulk_users
+      summary: Post Bulk Users
+      description: |
+        Post user metadata in bulk.
+        This metadata can be used to filter or to be included in recommendations and similars methods.
+      consumes:
+       - text/plain; charset=utf-8
+      parameters:
+        - name: body
+          in: body
+          description:  |
+            A number of user metadata objects separated with newlines.
+            Each user metadata object must have its id field.
+            Note that this is not a valid JSON data structure.
+            The body size is limited to 10 thousand lines.
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Bulk user metadata request executed.
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        209:
+          description: Some metadata is not uploaded successfully.
+          schema:
+            $ref: '#/definitions/BulkSchemaErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  /v1/items/_bulk:
+    post:
+      tags:
+        - metadata
+      operationId: post_bulk_items
+      summary: Post Bulk Items
+      description: |
+        Post item metadata in bulk.
+        This method is recommended for sharing stored data with SuggestGrid.
+      consumes:
+       - text/plain; charset=utf-8
+      parameters:
+        - name: body
+          in: body
+          description:   |
+            A number of item metadata objects separated with newlines.
+            Each item metadata object must have its id field.
+            Note that this is not a valid JSON data structure.
+            The body size is limited to 10 thousand lines.
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Bulk item metadata request executed.
+          schema:
+            $ref: '#/definitions/MessageResponse'
+        209:
+          description: Some metadata is not uploaded successfully.
+          schema:
+            $ref: '#/definitions/BulkSchemaErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  # Recommendation Paths
+  /v1/recommend/users:
+    post:
+      tags:
+        - recommendation
+      operationId: get_recommended_users
+      summary: Get Recommended Users
+      description: Recommend users for the given body parameters.
+      parameters:
+        - name: body
+          in: body
+          description: |
+            Parameters for recommend users method.
+          required: true
+          schema:
+            $ref: '#/definitions/GetRecommendedUsersBody'
+      responses:
+        200:
+          description: Similar users response.
+          schema:
+            $ref: '#/definitions/UsersResponse'
+        400:
+          description: Request body is invalid.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        422:
+          description: Required parameters are missing.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  /v1/recommend/items:
+    post:
+      tags:
+        - recommendation
+      operationId: get_recommended_items
+      summary: Get Recommended Items
+      description: Recommend items for the given body parameters.
+      parameters:
+        - name: body
+          in: body
+          description: |
+            Parameters for recommend items method.
+          required: true
+          schema:
+            $ref: '#/definitions/GetRecommendedItemsBody'
+      responses:
+        200:
+          description: |
+          schema:
+            $ref: '#/definitions/ItemsResponse'
+        400:
+          description: Request body is invalid.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        422:
+          description: Required parameters are missing.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  # Similarity Paths
+  /v1/similar/users:
+    post:
+      tags:
+        - similarity
+      operationId: get_similar_users
+      summary: Get Similar Users
+      description: Get similar users to a user.
+      parameters:
+        - name: body
+          in: body
+          description: Similar users method parameters.
+          required: true
+          schema:
+            $ref: '#/definitions/GetSimilarUsersBody'
+      responses:
+        200:
+          description: Similar users response.
+          schema:
+            $ref: '#/definitions/UsersResponse'
+        400:
+          description: Request body is invalid.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        422:
+          description: Required parameters are missing.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+  /v1/similar/items:
+    post:
+      tags:
+        - similarity
+      operationId: get_similar_items
+      summary: Get Similar Items
+      description: Get similar items to an item.
+      parameters:
+        - name: body
+          in: body
+          description: Similar items method parameter.
+          required: true
+          schema:
+            $ref: '#/definitions/GetSimilarItemsBody'
+      responses:
+        200:
+          description: |
+          schema:
+            $ref: '#/definitions/ItemsResponse'
+        400:
+          description: Request body is invalid.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        422:
+          description: Required parameters are missing.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        429:
+          description: Too many requests.
+          schema:
+            $ref: '#/definitions/ErrorResponse'
+        default:
+          description: Unexpected internal error.
+          schema:
+            $ref: '#/definitions/ErrorResponse'