swagger.yaml

swagger: '2.0'
info:
  version: '1.0.0'
  title: "[Hackathon] Adidas Wishlist API"
  contact:
      name: "Samir AMZANI / Ignacio Alzorriz"
      email: "samir.amzani@adidas.com"
  description: |
    A Simple adidas product API for the On-Boarding hackathon.
    [On-Boarding trainings](https://tools.adidas-group.com/confluence/display/DSBP/Engineers+On-Boarding+trainings) hackathon

    ## Affordances
    This API affords the following actions:
    - Retrieve the list of products
    - Retrieve a single product
    - Create a product
    - Update an existing product (status...)
    - Retrieve reviews about a product
    - Add a product review
    - Create a user
    - Retrieve user profile
    - Retrieve the user wishlist (TODO)
    - Add a product into the wishlist (TODO)
    - Delete a specific product from mt wishlist (TODO)
    - Clear the wishlist (TODO)


produces:
  - application/hal+json      # Representation message format
  - application/problem+json  # Error message format

schemes:
  - http

securityDefinitions:
  oauth2:
    type: oauth2
    authorizationUrl: 'http://example/oauth'
    description: |

      There are three available roles in the application:

        - Anonymous -> can log in, log out, see products, see general ratings from a product.
        - User -> all from Anonymous + following scopes: write:wishlist, read:reviews, write:reviews.
        - Admin -> all from Anonymous + following scopes: write:products, read:reviews, read:reviews:stats, read:users, write:users.
    flow: implicit
    scopes:
      'write:products': modify products
      'write:wishlist': read and modify your wishlist
      'read:reviews': read all reviews
      'write:reviews': write reviews
      'read:reviews:stats': read review statistics
      'read:users': read users
      'write:users': modify users

paths:
  /:
    x-summary: Wishlist

    get:
      summary: The API Root
      description: Retrieve the API Root

      responses:
        200:
          description: The root of the API
          schema:
            $ref: '#/definitions/halRoot'


  /products:
    x-summary: List of Products

    get:
      summary: Retrieve List of Products
      parameters:
        - name: offset
          in: query
          description: Number of results to skip from the start of the list
          required: false
          type: string
          default: '0'
          x-example: '10'
        - name: limit
          in: query
          description: The maximum number of reusults to return
          required: false
          type: string
          default: '10'
          x-example: '5'
        - name: status
          in: query
          description: Statuses to filter by. Retrieved products must match any of the given statuses.
          required: false
          type: array
          items:
            type: string
            enum: 
            - available
            - pending
            - sold
            - out
          collectionFormat: csv
        - name: tags
          in: query
          description: Tags to filter by. Retrieved products must match all given tags.
          required: false
          type: array
          items:
            type: number
          collectionFormat: csv
        - name: category
          in: query
          description: Category to filter by. Retrieved products must match given category.
          required: false
          type: number
      responses:
        200:
          description: The list of Products
          schema:
            $ref: '#/definitions/halProducts'

    post:
      summary: Create a New Product
      consumes:
        - application/json
      parameters:
        - name: Product
          in: body
          description: Product to be created
          required: true
          schema:
            $ref: '#/definitions/product'
      responses:
        201:
          description: Newly created product
          schema:
            $ref: '#/definitions/halProduct'
      security:
        - oauth2:
          - 'write:products'

  /products/{product_id}:
    x-summary: Product

    parameters:
      - name: product_id
        in: path
        description: Id of the Product
        required: true
        type: string
        x-example: 'DB1124'

    get:
      summary: Retrieve Product
      responses:
        200:
          description: A particular Product
          schema:
            $ref: '#/definitions/halProduct'
        404:
          description: The requested Product wasn't found
          headers:
            Content-Type:
              type: string
              default: application/problem+json
          schema:
            $ref: '#/definitions/productNotFound'

    patch:
      summary: Update Product
      consumes:
        - application/json
      parameters:
        - name: Product
          in: body
          description: Partial Product update
          required: true
          schema:
            $ref: '#/definitions/productPatch'
      responses:
        200:
          description: The Product was updated
          schema:
            $ref: '#/definitions/halProduct'
      security:
        - oauth2:
          - 'write:products'

  /products/{product_id}/reviews:

    x-summary: List of Product Reviews

    parameters:
      - name: product_id
        in: path
        description: Id of the Product
        required: true
        type: string
        x-example: 'DB1124'

    get:
      summary: Retrieve List of a Product Reviews
      parameters:
        - name: offset
          in: query
          description: Number of results to skip from the start of the list
          required: false
          type: string
          default: '0'
          x-example: '10'
        - name: limit
          in: query
          description: The maximum number of reusults to return
          required: false
          type: string
          default: '10'
          x-example: '5'
      responses:
        200:
          description: The list of Product review
          schema:
            $ref: '#/definitions/halReviews'
      security:
        - oauth2:
          - 'read:reviews'

    post:
      summary: Create a New Product Review
      consumes:
        - application/json
      parameters:
        - name: Review
          in: body
          description: Review to be created
          required: true
          schema:
            $ref: '#/definitions/review'
      responses:
        201:
          description: Newly created product
          schema:
            $ref: '#/definitions/halReview'
      security:
        - oauth2:
          - 'write:reviews'


  /users:

    x-summary: Users

    post:
      summary: Create a New User
      consumes:
        - application/json
      parameters:
        - name: Video
          in: body
          description: Video to be created
          required: true
          schema:
            $ref: '#/definitions/user'
      responses:
        201:
          description: Newly created video
          schema:
            $ref: '#/definitions/halUser'
      security:
        - oauth2:
          - 'write:users'

  /users/{user_id}:
    x-summary: User Profile

    parameters:
      - name: user_id
        in: path
        description: Id of the User
        required: true
        type: string
        x-example: 'xxxxx'

    get:
      summary: Get the User Profile
      responses:
        200:
          description: A particular User Profile
          schema:
            $ref: '#/definitions/halUser'
      security:
        - oauth2:
          - 'read:users'

definitions:
  #
  # API Root
  #
  halRoot:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /
        products:
          href: /products
        reviews:
          href: /reviews
        users:
          href: /users

  #
  # Product Resource
  #
  halProducts:
    type: object
    properties:
      productCount:
        type: number
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /products

        create:
          href: /products

        next:
          href: /products?offset=5&limit=5

        first:
          href: /products?offset=0&limit=5

        last:
          href: /products?offset=40&limit=5

      _embedded:
        product:
          - $ref: '#/definitions/halProduct/example'

  # Product HAL Wrapper
  halProduct:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
      - $ref: '#/definitions/product'
    example:
      _links:
        self:
          href: /products/DB1124

        edit:
          href: /products/DB1124

        delete:
          href: /products/DB1124
      id: 'DB1124'
      title: 'My Product title'
      description : 'An example of a product description'
      category: 'lorem'
      status: 'available'
      image: 'https://cdn.sportsshoes.com/product/A/ADI8522/ADI8522_200_1.jpg'
      tags: ['beyond', 'zapitilla', 'zaragoza']
      createdAt: '2017-06-21T14:07:17Z'


  # Partial Product
  productPatch:
    type: object
    allOf:
      - $ref: '#/definitions/product'
    example:
      status: 'out'

  # Product
  product:
    type: object
    properties:
      id:
        type: string
      title:
        type: string
      description:
        type: string
      category:
        type: string
      status:
        type: string
        enum:
        - available
        - pending
        - sold
        - out
        default: available
      images:
        type: string
      tags:
        type: array
        items:
          type: string
      createdAt:
        type: string
    required:
      - title
      - description
      - category
    example:
      id: 'DB1124'
      title: 'My Product title'
      description : 'An example of a product description'
      category: 'lorem'
      status: 'available'
      image: 'https://cdn.sportsshoes.com/product/A/ADI8522/ADI8522_200_1.jpg'
      tags: ['beyond', 'zapitilla', 'zaragoza']
      createdAt: '2017-06-21T14:07:17Z'


  # Product Not Found Error
  productNotFound:
    type: object
    allOf:
      - $ref: '#/definitions/problemDetail'
    example:
      title: 'Not Found'
      detail: 'Cannot find the requested product'
      status: 404
      instance: '/products/DB1124'


  #
  # Review Resource
  #
  halReviews:
    type: object
    properties:
      reviewCount:
        type: number
      averageRating:
        type: number
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /products/{product_id}/reviews
          templated: true

        create:
          href: /products/{product_id}/reviews
          templated: true

        next:
          href: /products/{product_id}/reviews?offset=5&limit=5
          templated: true

        first:
          href: /products/{product_id}/reviews?offset=0&limit=5
          templated: true

        last:
          href: /products/{product_id}/reviews?offset=40&limit=5
          templated: true

      _embedded:
        reviewCount: 122
        averageRating: 4.3
        review:
          - $ref: '#/definitions/halReview/example'

  # HAL Wrapper
  halReview:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
      - $ref: '#/definitions/review'
    example:
      _links:
        self:
          href: /products/{product_id}/reviews
          templated: true
      id: 'DB1124'
      comment: 'This is a review comment example'
      rating: 4.3
      createdAt: '2017-06-21T14:07:17Z'


  # Review
  review:
    type: object
    properties:
      id:
        type: string
      comment:
        type: string
      rating:
        type: number
      createdAt:
        type: string
    required:
      - comment
      - rating
    example:
      id: 'DB1124'
      comment: 'This is a review comment example'
      rating: 4.3
      createdAt: '2017-06-21T14:07:17Z'



  # HAL Wrapper
  halReviewStatsItem:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
      - $ref: '#/definitions/reviewStatsItem'
    example:
      date: '2017-06-21T14:07:17Z'
      rating: 4.3


  # Review Stats
  reviewStatsItem:
    type: object
    properties:
      id:
        type: string
      comment:
        type: string
      rating:
        type: number
      createdAt:
        type: string
        readOnly: true
    required:
      - comment
      - rating
    example:
      id: 'DB1124'
      comment: 'This is a review comment example'
      rating: 4.3
      createdAt: '2017-06-21T14:07:17Z'

#
  # User Resource
  #

  # HAL Wrapper
  halUser:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
      - $ref: '#/definitions/user'
    example:
      _links:
        self:
          href: /users/{user_id}
          templated: true
      id: '232333'
      username: 'Sam'
      createdAt: '2017-06-21T14:07:17Z'


  # Review
  user:
    type: object
    properties:
      id:
        type: string
      username:
        type: string
      password:
        type: string
      createdAt:
        type: string
    required:
      - username
      - password
    example:
      id: '232333'
      username: 'Sam'
      createdAt: '2017-06-21T14:07:17Z'

  # User Not Found Error
  userNotFound:
    type: object
    allOf:
      - $ref: '#/definitions/problemDetail'
    example:
      title: 'Not Found'
      detail: 'Cannot find any user with this id'
      status: 404
      instance: '/users/{user_id}'



  #
  # -- DO NOT EDIT BEYOND THIS POINT --
  #

  # Media Types Definitions

  #
  # application/problem+json
  #
  problemDetail:
    type: object
    properties:
      type:
        type: string
      title:
        type: string
      status:
        type: number
      detail:
        type: string
      instance:
        type: string
    required:
      - title
      - detail

  #
  # application/hal+json defintion
  #
  halLinkObject:
    type: object
    required:
      - href
    properties:
      href:
        type: string
      templated:
        type: boolean
      type:
        type: string
      deprecation:
        type: string
      name:
        type: string
      profile:
        type: string
      title:
        type: string
      hreflang:
        type: string

  halCuriesLink:
    title: HAL Curies Link
    allOf:
      - type: object
        properties:
          templated:
            enum:
              - true
        required:
          - templated
      - $ref: '#/definitions/halLinkObject'

  halResource:
    title: HAL Resource Object
    type: object
    properties:
      _links:
        type: object
        additionalProperties:
          # WARN: Should be "anyOf" but "anyOf" isn't supported in Swagger 2.0
          allOf:
            - $ref: '#/definitions/halLinkObject'
            - type: array
              items:
                - $ref: '#/definitions/halLinkObject'
        properties:
          curies:
            # WARN: Should be "anyOf" but "anyOf" isn't supported in Swagger 2.0
            allOf:
              - $ref: '#/definitions/halCuriesLink'
              - type: array
                items:
                  - $ref: '#/definitions/halCuriesLink'
      _embedded:
        type: object
        additionalProperties: true
        # WARN: Apiary doesn't support circular references
        # additionalProperties:
        #   anyOf:
        #     - $ref: '#/definitions/hal_resource'
        #     - type: array
        #       items:
        #         - $ref: '#/definitions/hal_resource'