Implemented the GET /users/{username}/inventory endpoint for the Open API specification document in the library target.

2025-10-17 17:10:17 +02:00
parent 63118db805
commit 9a9f0eb7d7
1 changed files with 278 additions and 3 deletions
@@ -231,9 +231,7 @@ tags:
  - name: Authentication
    description: Access data on authenticating to the service.
  - name: Database
-    description: Access data on artists, labels, and releases.    
-  - name: Marketplace
-    description: Interact with the marketplace, including listings, orders, and fees.
+    description: Access data on artists, labels, and releases.
  - name: User Identity
    description: Manage and retrieve user profile information, submissions, and contributions.
  - name: User Collection
@@ -242,6 +240,8 @@ tags:
    description: Manage a user's wantlist.
  - name: User Lists
    description: Manage user-created lists.
+  - name: Marketplace
+    description: Interact with the marketplace, including listings, orders, and fees.
  - name: Inventory Management
    description: Bulk inventory management via CSV uploads and exports.
 paths:
@@ -1815,6 +1815,69 @@ paths:
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
+  /users/{username}/inventory:
+    get:
+      tags:
+        - Marketplace
+      summary: Get the listings in an inventory of a seller.
+      description: |
+        Returns the list of listings for an inventory of a user. 
+
+        Basic information about each listing and the corresponding release is provided, suitable for display in a list. For detailed information about the release, make another API call to fetch the corresponding Release.
+
+        This endpoints accepts pagination and also, in case of authenticated as an inventory owner, items that not only have the `For Sale` state will be shown as well as other  extra fields in those items such as `weight`, `format_quality`, `external_id`, `location`, and `quantity_keys`. Note that the `quantity` field is read-only for *NearMint* users, who will see *1* for all quantity values, regardless of their actual count. 
+        
+        In case the user is authorized, the listing will contain a `in_cart` boolean field indicating whether or not this listing is in their cart.
+      operationId: getInventory
+      parameters:
+        - $ref: '#/components/parameters/Username'
+        - $ref: '#/components/parameters/InventoryStatus'
+        - $ref: '#/components/parameters/SortInventory'
+        - $ref: '#/components/parameters/SortOrder'
+        - $ref: '#/components/parameters/Page'
+        - $ref: '#/components/parameters/PerPage'
+      responses:
+        '200':
+          description: Successfully retrieved the list of listings in an inventory of a seller.
+          headers:
+            Link:
+              $ref: '#/components/headers/Link'
+            X-Discogs-RateLimit:
+              $ref: '#/components/headers/RateLimit'
+            X-Discogs-RateLimit-Used:
+              $ref: '#/components/headers/RateLimitUsed'
+            X-Discogs-RateLimit-Remaining:
+              $ref: '#/components/headers/RateLimitRemaining'
+          content:
+            application/json:
+              schema:
+                description: A type that contains a list of listing in an inventory of a user.
+                type: object
+                properties:
+                  pagination:
+                    $ref: '#/components/schemas/Pagination'
+                  listings:
+                    description: A list of listings in an inventory of a user.
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Listing'
+                required:
+                  - listings
+                  - pagination
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          $ref: '#/components/responses/Unprocessable'
+        '500':
+          $ref: '#/components/responses/InternalError'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          $ref: '#/components/responses/Unprocessable'
+        '500':
+          $ref: '#/components/responses/InternalError'
 components:
  headers:
    Link:
@@ -1961,6 +2024,21 @@ components:
        type: integer
        minimum: 0
      example: 3
+    InventoryStatus:
+      description: A status of a inventory.
+      name: status
+      in: query
+      schema:
+        type: string
+        enum:
+          - All
+          - For Sale
+          - Draft
+          - Expired
+          - Sold
+          - Violation
+          - Suspended
+          - Deleted
    Label:
      description: A filter by label.
      name: label
@@ -2085,6 +2163,22 @@ components:
          - rating
          - year
          - added
+    SortInventory:
+      description: A filter by an inventory field.
+      name: sort
+      in: query
+      schema:
+        type: string
+        enum: 
+          - listed
+          - price
+          - item
+          - artist
+          - label
+          - catno
+          - audio
+          - status
+          - location
    SortOrder:
      description: The order to sort the results. 
      name: sort_order
@@ -2167,6 +2261,14 @@ components:
            $ref: '#/components/schemas/ServiceError'
          example:
            message: Server is currently unavailable.
+    Unprocessable:
+      description: An invalid parameter has been sent
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ServiceError'
+          example:
+            message: Invalid parameter - expected one of accepted values.
  schemas:
    Artist:
      description: A type that represents an artist or a group.
@@ -2371,6 +2473,33 @@ components:
      required:
        - have
        - want
+    ConditionMedia:
+      description: A type that represents a media condition.
+      type: string
+      enum:
+        - Mint (M)
+        - Near Mint (NM or M-)
+        - Very Good Plus (VG+)
+        - Very Good (VG)
+        - Good Plus (G+)
+        - Good (G)
+        - Fair (F)
+        - Poor (P)
+    ConditionSleeve:
+      description: A type that represents a sleeve condition.
+      type: string
+      enum:
+        - Mint (M)
+        - Near Mint (NM or M-)
+        - Very Good Plus (VG+)
+        - Very Good (VG)
+        - Good Plus (G+)
+        - Good (G)
+        - Fair (F)
+        - Poor (P)
+        - Generic
+        - Not Graded
+        - No Cover
    Currency:
      description: A list of currency codes defined in the marketplace.
      type: string
@@ -2774,6 +2903,96 @@ components:
        - public
        - resource_url
        - url
+    Listing:
+      description: A type that represents a listing.
+      type: object
+      properties:
+        id:
+          description: An identifier of a listing.
+          type: integer
+          minimum: 0
+          readOnly: true
+        uri:
+          description: A URI representation of a listing.
+          type: string
+          format: uri
+          readOnly: true
+        resource_url:
+          description: A URI resource of a listing.
+          type: string
+          format: uri
+          readOnly: true
+        status:
+          description: A status of a listing.
+          type: string
+          enum:
+            - Draft
+            - Expired
+            - For Sale
+            - Sold
+        price:
+          description: A price assigned to a listing.
+          $ref: '#/components/schemas/Price'
+        allow_offers:
+          description: A flag that indicates whether a listing allow to receive offers or not.
+          type: boolean
+        condition:
+          description: A media condition of a listing.
+          $ref: '#/components/schemas/ConditionMedia'
+        sleeve_condition: 
+          description: A sleeve condition of a listing.
+          $ref: '#/components/schemas/ConditionSleeve'
+        posted:
+          description: A date and time a listing was posted in the marketplace.
+          type: string
+          format: date-time
+        ships_from:
+          description: A country from where a listing will be shipped.
+          type: string
+        comments:
+          description: A comment related to a listing.
+          type: string
+        seller:
+          description: A seller of a listing.
+          $ref: '#/components/schemas/UserId'
+        release:
+          description: A release of a listing.
+          $ref: '#/components/schemas/ReleaseInListing'
+        audio:
+          description: A flag that indicates whether is an audio listing or not.
+          type: boolean
+        external_id:
+          description: Any private comment for the seller, if any.
+          type: string
+        format_quantity:
+          description: A number of units this listing counts as for shipping, if any.
+          type: integer
+          minimum: 1
+        location:
+          description: A geographical location of a listing, if any.
+          type: string
+        weight:
+          description: A weight in grams of a listing, if any.
+          type: integer
+          minimum: 0
+        in_cart:
+          description: A flag that indicates whether a listing is in the shopping cart of a user.
+          type: boolean
+      required:
+        - allow_offers
+        - audio
+        - comments
+        - condition
+        - id
+        - posted
+        - price
+        - release
+        - resource_url
+        - seller
+        - ships_from
+        - sleeve_condition
+        - status
+        - uri
    Master:
      description: A type that represents a set of similar releases.
      type: object
@@ -2845,6 +3064,20 @@ components:
        - per_page
        - items
        - urls
+    Price:
+      description: A type that represents a price.
+      type: object
+      properties:
+        currency: 
+          $ref: '#/components/schemas/Currency'
+        value:
+          description: A decimal number of a price.
+          type: number
+          format: float
+          minimum: 0
+      required:
+        - currency
+        - value
    Rating: 
      description: A type that represents a community rating of a release.
      type: object
@@ -2996,6 +3229,23 @@ components:
        - styles
        - title
        - uri
+    ReleaseId:
+      description: A type that referenced a release.
+      type: object
+      properties:
+        id:
+          description: An identifier of a release.
+          type: integer
+          minimum: 0
+          readOnly: true
+        resource_url:
+          description: A URI resource of a release.
+          type: string
+          format: uri
+          readOnly: true
+      required:
+        - id
+        - resource_url
    ReleaseInFolder:
      description: A type that represents an appearance of a release in a collection folder of a user.
      type: object
@@ -3050,6 +3300,31 @@ components:
        - basic_information
        - id
        - date_added
+    ReleaseInListing:
+      description: A type that represents a release in a listing.
+      allOf:
+        - $ref: '#/components/schemas/ReleaseId'
+        - type: object
+          properties:
+            catalog_number:
+              description: A catalog number of a release.
+              type: string
+            description:
+              description: A descriptive explanation of a release.
+              type: string
+            thumbnail:
+              description: A thumbnail image of a release.
+              type: string
+              format: uri
+            year:
+              description: A number of year of a release.
+              type: integer
+              minimum: 1800
+          required:
+            - catalog_number
+            - description
+            - thumbnail
+            - year
    ReleaseInstance:
      description: A type that represents an instace of a release.
      type: object