swagger: '2.0' info: version: 0.0.1 title: OWS Product API Spec description: '' host: qa-ows-product.theorchard.io tags: - name: health description: Healthcheck - name: vendor description: Vendor related endpoints - name: subaccount description: Subaccount related endpoints - name: product description: Product related endpoints - name: localization description: Localization related endpoints - name: language description: Language related endpoints - name: upc description: UPC related endpoints paths: /hello/: get: tags: - health description: Check the health of the application. responses: 200: description: 200 OK examples: application/json: status: ok /lookup/products/ownership/: post: tags: - product description: | Dataloader-style endpoint returns ownership attributes for a list of products. parameters: - in: body name: product_ids description: List of product ids. required: true schema: type: array items: type: integer responses: 200: description: | HTTP 200 OK ----------- Returns list of products ownership. examples: application/json: product_ids: - product_id: 1 tenant_type: subaccount tenant_id: 123 - product_id: 3 tenant_type: account tenant_id: 6971 - null 400: description: | HTTP 400 BAD REQUEST -------------------- When the request body does not contain product ids When the request body contains non-integer product ids /vendor/{vendor_id}/product/{product_id}: head: tags: - vendor description: Verify a product is owned by a vendor. parameters: - name: vendor_id in: path required: true type: string - name: product_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: Product is owned by account. 400: description: Request parameter/header validation failure. 403: description: Product not owned by account or not authorized to check ownership for account. 404: description: Could not find product with product_id. /vendor/{vendor_id}/product_code/{product_code}: head: tags: - vendor description: Verify a product code used by a vendor. parameters: - name: vendor_id in: path required: true type: string - name: product_code in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: Product is used by vendor. 400: description: Request parameter/header validation failure. 404: description: Could not find a product for vendor with product_code. /vendor/{vendor_id}/products: get: tags: - vendor description: | Returns list of products sorted by release date descending for a given vendor id. Defaults to filtering by status of label_processing if no status filter is provided. parameters: - name: vendor_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false - name: status in: query description: Release status to filter list of products. "all" returns products with any status. enum: ["label_processing", "transfer_to_content", "in_content", "all"] required: false type: string default: label_processing - name: page_offset in: query description: Offset for pagination. type: string pattern: ^\d+$ required: false - name: page_limit in: query description: Max number of results per page. type: string pattern: ^[1-9]\d*$ required: false responses: 200: description: | HTTP 200 OK. --------------- JSON object containing a paginated array of products from the vw_product view. headers: Correlation-Id: type: string description: UUID to correlate logs (echoes back correlation_id from request header). examples: application/json: items: - product_id: 12345 distribution_format_id: 1 product_type_id: 1 project_id: 1234 upc: '112344567889' product_name: Charlie Dance release_date: '2016-08-08' status: label_processing - product_id: 12346 distribution_format_id: 1 product_type_id: 1 project_id: 1234 upc: '112344567111' product_name: Charlie Song release_date: '2016-10-15' status: label_processing pagination: type: standard offset: 0 limit: 50 total_records: 2 400: description: Request parameter/header validation failure. 403: description: Not authorized to check ownership for account. /vendor/{vendor_id}/display_upc/{display_upc}: get: tags: - vendor description: Get a vendor's upc by display_upc and context_type. parameters: - name: vendor_id in: path required: true type: string - name: display_upc in: path required: true type: string - name: context_type in: query description: The context_type of the product. enum: ["digital", "physical"] required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: OK. Response contains a JSON array of one product object. headers: Correlation-Id: type: string description: UUID to correlate logs (echoes back correlation_id from request header). 400: description: Bad Request. Request parameter/header validation failure. 403: description: Grass denied access. 404: description: No product found that matches parameters. /vendor/{vendor_id}/display_upc/{display_upc}/available: head: tags: - vendor description: Check if display_upc is actively used by vendor. parameters: - name: vendor_id in: path required: true type: string - name: display_upc in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: display_upc is available for use. 400: description: Request parameter/header validation failure. 403: description: UPC not available or client not authorized to check availability for account. /subaccount/{subaccount_id}/product/{product_id}: head: tags: - subaccount description: Verify a product is owned by a subaccount. parameters: - name: subaccount_id in: path required: true type: string - name: product_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: Product is owned by account. 400: description: Request parameter/header validation failure. 403: description: Product not owned by account or not authorized to check ownership for account. 404: description: Could not find product with product_id. /subaccount/{subaccount_id}/product_code/{product_code}: head: tags: - subaccount description: Verify a product code used by a subaccount. parameters: - name: subaccount_id in: path required: true type: string - name: product_code in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: Product is used by vendor. 400: description: Request parameter/header validation failure. 404: description: Could not find a product for vendor with product_code. /subaccount/{subaccount_id}/products: get: tags: - subaccount description: | Returns list of products sorted by release date descending for a given subaccount id. Defaults to filtering by status of label_processing if no status filter is provided. parameters: - name: subaccount_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false - name: status in: query description: Release status to filter list of products. enum: ["label_processing", "transfer_to_content", "in_content"] required: false type: string default: label_processing - name: page_offset in: query description: Offset for pagination. type: string pattern: ^\d+$ required: false - name: page_limit in: query description: Max number of results per page. type: string pattern: ^[1-9]\d*$ required: false responses: 200: description: | HTTP 200 OK. --------------- JSON object containing a paginated array of products from the vw_product view. headers: Correlation-Id: type: string description: UUID to correlate logs (echoes back correlation_id from request header). examples: application/json: items: - product_id: 12345 distribution_format_id: 1 product_type_id: 1 project_id: 1234 upc: '112344567889' product_name: Charlie Dance release_date: '2016-08-08' status: label_processing - product_id: 12346 distribution_format_id: 1 product_type_id: 1 project_id: 1234 upc: '112344567111' product_name: Charlie Song release_date: '2016-10-15' status: label_processing pagination: type: standard offset: 0 limit: 50 total_records: 2 400: description: Request parameter/header validation failure. 403: description: Not authorized to check ownership for account. /subaccount/{subaccount_id}/display_upc/{display_upc}/available: head: tags: - subaccount description: Check if a display_upc is actively used by subaccount. parameters: - name: subaccount_id in: path required: true type: string - name: display_upc in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: display_upc is available for use. 400: description: Request parameter/header validation failure. 403: description: UPC not available or client not authorized to check availability for account. /product/{product_id}: get: tags: - product description: Get product by product id and confirm ownership, if ownership informaton is provided. parameters: - name: product_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: | HTTP 200 OK. --------------- JSON object representing immutable product information from the vw_product view. headers: Correlation-Id: description: UUID to correlate logs (echoes back correlation_id from request header). type: string examples: application/json: product_id: 1234 project_id: 1111 distribution_format_id: 2 product_type_id: 1 upc: 100075236325 vendor_id: 7123 subaccount_id: 0 context_type: digital release_date: '2016-10-15' status: label_processing product_name: Charlie Dance 400: description: Request parameter/header validation failure. 403: description: Product not owned by account or not authorized to check ownership for account. 404: description: Could not find product with product_id. delete: tags: - product description: Deletes a product record with given productId parameters: - name: product_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: | HTTP 200 OK -------------------- The product was successfully deleted. 400: description: | HTTP 400 Bad Request -------------------- Product ownership check fail. The request was not formatted correctly. - Could be because a product status is not `label_processing` examples: application/json: code: validation_error message: release_status: | 'release_status' must be `label_processing` to delete a product.' 404: description: | HTTP 404 Not Found -------------------- The product does not exist. /product/{product_id}/copy: post: tags: - product consumes: - application/json description: Copy the product. parameters: - name: product_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false - name: Orchard-User-Id in: header description: Orchard User Id type: string required: true - in: body name: body description: Product fields to override. required: true schema: $ref: "#/definitions/CopyProductPayload" responses: 200: description: | HTTP 200 OK ----------- Returns the product_id of the new product. examples: application/json: product_id: 123456 400: description: | HTTP 400 Bad Request -------------------- The request was not formatted correctly. Product ownership check fail. 404: description: | HTTP 404 Not Found ------------------ The product does not exist. /bulk-upc: post: tags: - product consumes: - application/json description: Get products by respective upcs. parameters: - in: body name: upcs description: List of UPC. required: true schema: type: array items: type: string responses: 200: description: | HTTP 200 OK. --------------- Returns a list of products. examples: application/json: items: - product_id: 1 upc: '123' display_upc: '123' product_type: 'Music' product_name: 'Release Name 1' context_type: 'digital' vendor_id: 1234 subaccount_id: 0 release_date: '2018-01-01' - product_id: 2 upc: '456' display_upc: '456' product_type: 'Movie' product_name: 'Release Name 2' context_type: 'digital' vendor_id: 5678 subaccount_id: 2456 release_date: '2018-02-01' 400: description: | HTTP 400 Bad Request -------------------- The request body does not include upcs or if upcs list contains more than 100 items. 404: description: | HTTP 404 Not Found ------------------ All upcs provided are not valid. /product/{product_id}/document: get: tags: - product consumes: - application/json description: Get a fully-hydrated document-store representation of a product. parameters: - name: product_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false - name: Orchard-User-Id in: header description: Orchard User Id type: string required: false responses: 200: description: | HTTP 200 OK ----------- Return the JSON document of the product. schema: $ref: "#/definitions/ProductDocumentResponse" 404: description: | HTTP 404 Not Found ------------------ The product does not exist. /product/upc/{upc}: get: tags: - product description: Get product by upc. parameters: - name: upc in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: | HTTP 200 OK. --------------- JSON object representing immutable product information from the vw_product view. headers: Correlation-Id: type: string description: UUID to correlate logs (echoes back correlation_id from request header). examples: application/json: product_id: 1234 project_id: 1111 distribution_format_id: 2 product_type_id: 1 upc: 100075236325 vendor_id: 7123 subaccount_id: 0 400: description: Request parameter/header validation failure. 403: description: Product not owned by account or not authorized to check ownership for account. 404: description: Could not find product with upc. /product/upc/{upc}/is_orchard_upc: get: tags: - product description: Check if a UPC is an Orchard UPC. parameters: - name: upc in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string responses: 200: description: Successful request. examples: application/json: is_orchard_upc: true 404: description: UPC is not an integer. /product/{account_type}/{account_uuid}/product_code/{product_code}: get: tags: - product description: Get product (contains only product_id at the moment) by product_code and account. parameters: - name: account_type in: path required: true type: string - name: account_uuid in: path required: true type: integer - name: product_code in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Orchard-Profile-Type in: header description: Orchard Profile type. type: string required: true - name: Orchard-Profile-Id in: header description: Orchard Profile id. pattern: ^\d+$ type: string required: true - name: Orchard-Roles in: header description: Orchard Roles. type: string required: true responses: 200: description: | HTTP 200 OK. --------------- JSON object representing immutable product information from the vw_product view. headers: Correlation-Id: type: string description: UUID to correlate logs (echoes back correlation_id from request header). examples: application/json: product_id: 1234 400: description: Request validation failure or multiple records were found for the passed parameters. 404: description: Could not find product matching to the passed parameters. /product/{product_id}/phonetic-translations/{language_id}: get: tags: - product description: Get the phonetic translations for a product for a language parameters: - name: product_id in: path required: true type: string - name: language_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ['vendor', 'subaccount'] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: | HTTP 200 OK. --------------- JSON object containing an array of phonetic translation items for this product. headers: Correlation-Id: type: string description: UUID to correlate logs (echoes back correlation_id from request header). examples: application/json: items: - release_phonetic_translations_id: 1 release_id: 1 language_id: 1 field_name: 'title' phonetic_translation: 'phonetic translation for title' - release_phonetic_translations_id: 2 release_id: 2 language_id: 2 field_name: 'title' phonetic_translation: 'phonetic translation for title' 400: description: Request parameter/header validation failure. 403: description: Product not owned by account or not authorized to check ownership for account. 404: description: Could not find product with product_id. /product/{product_id}/phonetic-translations: get: tags: - product description: Get the phonetic translations for a product for all available languages parameters: - name: product_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ['vendor', 'subaccount'] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false responses: 200: description: | HTTP 200 OK. --------------- JSON object containing an array of phonetic translation items for this product. headers: Correlation-Id: type: string description: UUID to correlate logs (echoes back correlation_id from request header). examples: application/json: items: - release_phonetic_translations_id: 1 release_id: 1 language_id: 1 field_name: 'title' phonetic_translation: 'phonetic translation for title' - release_phonetic_translations_id: 2 release_id: 2 language_id: 2 field_name: 'title' phonetic_translation: 'phonetic translation for title' 400: description: Request parameter/header validation failure. 403: description: Product not owned by account or not authorized to check ownership for account. 404: description: Could not find product with product_id. post: consumes: - application/json tags: - product description: Creates new phonetic translations for a product parameters: - name: product_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ['vendor', 'subaccount'] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false - in: body name: body schema: $ref: "#/definitions/PhoneticTranslationsPayload" description: | The translations for the product. example: ```json { "release_id": 1, "field_name": "title", "language_id": 1, "phonetic_translation": "phonetic translation for title" } responses: 200: description: | HTTP 200 OK. --------------- JSON object containing an array of phonetic translation items for this product. headers: Correlation-Id: type: string description: UUID to correlate logs (echoes back correlation_id from request header). examples: application/json: items: - release_phonetic_translations_id: 1 release_id: 1 language_id: 1 field_name: 'title' phonetic_translation: 'phonetic translation for title' - release_phonetic_translations_id: 2 release_id: 2 language_id: 2 field_name: 'title' phonetic_translation: 'phonetic translation for title' 400: description: Request parameter/header validation failure. 403: description: Product not owned by account or not authorized to check ownership for account. 404: description: Could not find product with product_id. put: consumes: - application/json tags: - product description: Updates phonetic translations for a product parameters: - name: product_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ['vendor', 'subaccount'] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false - in: body name: body schema: $ref: "#/definitions/PhoneticTranslationsPayload" description: | The translations for the product. example: ```json { "release_phonetic_translations_id": 1, "release_id": 1, "field_name": "title", "language_id": 1, "phonetic_translation": "phonetic translation for title" } responses: 200: description: | HTTP 200 OK. --------------- JSON object containing an array of phonetic translation items for this product. headers: Correlation-Id: type: string description: UUID to correlate logs (echoes back correlation_id from request header). examples: application/json: items: - release_phonetic_translations_id: 1 release_id: 1 language_id: 1 field_name: 'title' phonetic_translation: 'phonetic translation for title' - release_phonetic_translations_id: 2 release_id: 2 language_id: 2 field_name: 'title' phonetic_translation: 'phonetic translation for title' 400: description: Request parameter/header validation failure. 403: description: Product not owned by account or not authorized to check ownership for account. 404: description: Could not find product with product_id. delete: consumes: - application/json tags: - product description: Deletes phonetic translations for a product. If no body is sent all translations will be deleted by product_id. parameters: - name: product_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ['vendor', 'subaccount'] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false - in: body required: false name: body schema: $ref: "#/definitions/PhoneticTranslationsPayload" description: | Array of release_phonetic_translation_id values to be deleted. responses: 200: description: | HTTP 200 OK. --------------- Message in the form of 'X phonetic translations deleted.' where X is the count of deleted translations. headers: Correlation-Id: type: string description: UUID to correlate logs (echoes back correlation_id from request header). 400: description: Request parameter/header validation failure. 403: description: Product not owned by account or not authorized to check ownership for account. 404: description: Could not find product with product_id. /localization/product/{product_id}: get: description: Get localization for a product by productId. tags: - localization parameters: - name: product_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: legacy in: query type: number description: 1 to use legacy tables. required: false responses: 200: description: | HTTP 200 OK. ------------ JSON object representing immutable localization information from dev-product_localization table. headers: Correlation-Id: description: UUID to correlate logs (echoes back correlation_id from request header). type: string examples: application/json: example: product_id: 1234 items: - language_id: 1 product_name: Hunt short_synopsis: test long_synopsis: test long - language_id: 12 product_name: Cazar short_synopsis: test 222 long_synopsis: test long 222 pagination: type: standard offset: 0 limit: 50 total_records: 2 legacy_example: pagination: type: standard limit: -1 total_records: 2 offset: 0 product_id: 1709044 items: - language_id: 1 product_name: Release-Afr delivered_version: Live-Afr remixer: '3105892': one translated artist - language_id: 2 product_name: Release-Ara delivered_version: Live-Ara featuring: '3105890': translated for artist 3105890 '3105891': translated for artist 3105891 400: description: Request parameter/header validation failure. 404: description: Could not find product with productId or language with languageid. /localization/product/{product_id}/language/{language_id}: delete: tags: - localization description: Deletes localization record for a given productId & languageId. parameters: - name: product_id in: path required: true type: string - name: language_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: legacy in: query type: number description: 1 to use legacy tables. required: false responses: 200: description: | HTTP 200 OK. ------------ The product was successfully deleted. -- LEGACY -- HTTP 200 OK. ------------ Successfully deleted release and artist localizations. 404: description: | HTTP 404 Not Found. ------------------- The product or language does not exist. post: consumes: - application/json tags: - localization description: Creates a localization entry for a given product and language. parameters: - name: product_id in: path required: true type: string - name: language_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: true type: string - name: Content-Type in: header required: true type: string pattern: ^application/json$ - name: legacy in: query type: number description: 1 to use legacy tables. required: false - in: body name: body description: | The fields to translate. Here are new and legacy post body examples: example: ```json { "product_name": "Translated name", "short_synopsis": "Translated test", "long_synopsis": "Translated test long" } ``` legacy_example: ```json { "product_name": "Translated release name", "delivered_version": "Translated product version", "performer": { "3427519":"translated name for artist 3427519", "4044560":"translated name for artist 4044560" }, "composer" : { "4044558":"translated name for artist 4044558" } } ``` required: true schema: $ref: "#/definitions/PostProductLanguagePayload" responses: 200: description: | HTTP 200 OK. ------------ JSON object representing the localization obj created/updated. headers: Correlation-Id: description: UUID to correlate logs (echoes back correlation_id from request header). type: string examples: application/json: product_id: 1234 localizations: language_id: 1 product_name: Translated name short_synopsis: Translated test long_synopsis: Translated test long 400: description: | HTTP 400 Bad Request. --------------------- The body contains the fields that did not pass validation with a validation context message. examples: application/json: message: product_name: '''product_name'' is a required property' code: bad_request /localization/track/{tuids}: get: tags: - localization description: Get localization for a track by tuids. parameters: - name: tuids in: path required: true type: string description: comma-separated track ids - name: Correlation-Id description: UUID in: header required: false type: string responses: 200: description: | HTTP 200 OK. ------------ JSON object representing localization information from track_localized_metadata & track_artist_localized_metadata table. single_21363833: ```json { "pagination": { "type": "none", "total_records": 2 }, "items": [ { "language_id": 1, "artists": { "69153652": "NEW Track Composer-Afr", "69153654": "NEW Track Artist-Afr", "69153662": "NEW Track Featuring-Afr" }, "track_name": "22 track2-Afr", "version": "22 Version-afr", "tuid": 21363833 }, { "language_id": 2, "artists": { "69153652": "Track Composer-Ara", "69153654": "Track Artist-Ara", "69153662": "Track Featuring-Ara" }, "track_name": "track2-Ara", "version": "Version-Ara", "tuid": 21363833 } ] } ``` multiple_21363833_21236647: ```json { "pagination": { "type": "none", "total_records": 6 }, "items": [ { "language_id": 1, "artists": { "69153652": "NEW Track Composer-Afr", "69153654": "NEW Track Artist-Afr", "69153662": "NEW Track Featuring-Afr" }, "track_name": "22 track2-Afr", "version": "22 Version-afr", "tuid": 21363833 }, { "language_id": 1, "artists": { "67486760": "NEW Track Featuring-Afr" }, "track_name": "22 track2-Afr", "version": "22 Version-afr", "tuid": 21236647 }, { "language_id": 2, "artists": { "69153652": "Track Composer-Ara", "69153654": "Track Artist-Ara", "69153662": "Track Featuring-Ara" }, "track_name": "track2-Ara", "version": "Version-Ara", "tuid": 21363833 }, { "language_id": 12, "artists": { "67486760": "artist 44", "67486761": "artist 44" }, "track_name": "trans name", "version": "trans 44", "tuid": 21236647 }, { "language_id": 6, "artists": { "67486761": "FR for 61" }, "track_name": "Track-Chinese-sim", "version": "", "tuid": 21236647 }, { "language_id": 7, "track_name": "Trck chinese tra", "version": "", "tuid": 21236647 } ] } ``` headers: Correlation-Id: description: UUID to correlate logs (echoes back correlation_id from request header). type: string delete: tags: - localization description: Deletes localization records for given tuids. parameters: - name: tuids in: path required: true type: string description: comma-separated track ids - name: Correlation-Id description: UUID in: header required: false type: string responses: 200: description: | HTTP 200 OK. ------------ 2 track localizations deleted. /localization/track/{tuid}/language/{language_id}: delete: tags: - localization description: Deletes localization records for a given tuid. parameters: - name: tuid in: path required: true type: string - name: language_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: true type: string responses: 200: description: | HTTP 200 OK. ------------ 1 track localizations deleted. put: tags: - localization description: Creates a localization entry for a given track and language. parameters: - name: tuid in: path required: true type: string - name: language_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: true type: string - name: Content-Type in: header required: true type: string pattern: ^application/json$ - in: body name: body description: | The fields to translate. example: ```json { "artists": { "67486758": "NEW Track Composer-Afr", "67486759": "NEW Track Artist-Afr", "67486760": "NEW Track Featuring-Afr" }, "version": "22 Version-afr", "track_name": "22 track2-Afr", } ``` required: true schema: $ref: "#/definitions/PutTrackLocalizationPayload" responses: 200: description: | HTTP 200 OK. ------------ JSON object representing the localization obj created/updated. headers: Correlation-Id: description: uid to correlate logs (echoes back correlation_id from request header). type: string examples: application/json: language_id: 1 artists: '67486758': NEW Track Composer-Afr '67486759': NEW Track Artist-Afr '67486760': NEW Track Featuring-Afr track_name: 22 track2-Afr tuid: 21236647 version: 22 Version-afr 400: description: | HTTP 400 Bad Request. --------------------- The body contains the fields that did not pass validation with a validation context message OR when the artist data is not a valid dict format. ## examples: missing_track_name: ```json { "message": { "track_name": "'track_name' is a required property" }, "code": "bad_request" } ``` missing_version: ```json { "message": { "version": "'version' is a required property" }, "code": "bad_request" } ``` invalid_artists_data: ```json { "code": "invalid_data", "message": "Invalid data sent for save track artist localization." } ``` 404: description: | HTTP 404 not Found. --------------------- If the language id is invalid in the url. examples: application/json: message: No Itunes Language found for this language_id. code: not_found_error /localization/tracks: put: consumes: - application/json tags: - localization description: Update several localizations for multiple TUIDs in different languages. parameters: - name: Correlation-Id description: UUID in: header required: true type: string - name: Content-Type in: header required: true type: string pattern: ^application/json$ - in: body name: body description: | The items to translate example: ```json { "items": [ { "language_id": 1, "tuid": 1, "track_name": "Translated Name", "version": "Translated Version", "artists": { "3230": "Translated Performer 1", "2456": "Translated Performer 2", "3123": "Translated Featured", "3124": "Translated Remixer" } }, { "language_id": 2, "tuid": 1, "track_name": "Translated2 Name", "version": "Translated Version", "artists": { "3123": "Translated Featured", "3124": "Translated Remixer" } }, { "language_id": 1, "tuid": 2, "track_name": "Translated Track Name", "version": "Translated Version", "artists": { "3300": "Translated Performer 1", "3301": "Translated Performer 2", } }, ] } ``` required: true schema: $ref: "#/definitions/PutBulkTrackLocalizationsPayload" responses: 200: description: | HTTP 200 OK. ------------ JSON object representing the localization obj created/updated. headers: Correlation-Id: description: uid to correlate logs (echoes back correlation_id from request header). type: string examples: application/json: items: - language_id: 1 tuid: 1 track_name: Translated Name version: Translated Version artists: '2456': Translated Performer 2 '3123': Translated Featured '3124': Translated Remixer '3230': Translated Performer 1 - language_id: 2 tuid: 1 track_name: Translated2 Name version: Translated Version artists: '3123': Translated Featured '3124': Translated Remixer - language_id: 1 tuid: 2 track_name: Translated Track Name version: Translated Version artists: '3300': Translated Performer 1 '3301': Translated Performer 2 400: description: | HTTP 400 Bad Request. --------------------- The body contains the fields that did not pass validation with a validation context message OR when the artist data is not a valid dict format. examples: missing_track_name: ```json { "message": { "track_name": "'track_name' is a required property" }, "code": "bad_request" } ``` missing_version: ```json { "message": { "version": "'version' is a required property" }, "code": "bad_request" } ``` invalid_artists_data: ```json { "code": "invalid_data", "message": "Invalid data sent for save track artist localization." } ``` /languages: get: tags: - language description: Get all languages for localizations sorted alphabetically. parameters: - name: Correlation-Id description: UUID in: header required: false type: string responses: 200: description: | HTTP 200 OK. ------------ JSON object representing immutable localization information from itunes_languages table. headers: Correlation-Id: description: UUID to correlate logs (echoes back correlation_id from request header). type: string examples: application/json: items: - id: 1 code: af name: Afrikaans meta_language_code: AFR - id: 2 code: ar name: Arabic meta_language_code: AFR - id: 3 code: bg name: Bulgarian meta_language_code: BUL pagination: type: standard offset: 0 limit: 100 total_records: 3 /upc/placeholder: post: tags: - upc description: Generate a number to be used as upc in releases table. parameters: - name: Correlation-Id description: UUID in: header required: false type: string responses: 200: description: | HTTP 200 OK. --------------- JSON object containing generated placeholder upc headers: Correlation-Id: description: UUID to correlate logs (echoes back correlation_id from request header). type: string examples: application/json: placeholder_upc: 12345678901234 /upc/{upc}: head: tags: - upc description: Check if a product exists with the given UPC. parameters: - name: upc in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string responses: 200: description: The UPC is in the upc table or being used by a product 404: description: The UPC is not being used /upc/available/{upc}: head: tags: - upc description: Check if a UPC is used with any products or is reserved. parameters: - name: upc in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string responses: 200: description: The UPC is available for use. 403: description: The UPC is not available for use. /upc/available: post: tags: - upc description: Check to see if a set of UPCs are used with any products or reserved. parameters: - name: upcs in: body required: true description: | Array of UPCs to check for availability. example: ```json { "upcs": [ 196872723823, 196872750799, 196872750560, 196872751116 ] } ``` responses: 200: description: | HTTP 200 OK. --------------- JSON object containing retrieved upc headers: Correlation-Id: description: UUID to correlate logs (echoes back correlation_id from request header). type: string examples: application/json: upcs: - 196872750799 - 196872750560 /upc/{upc}/is_orchard_upc: get: tags: - upc description: Check if a UPC is an Orchard UPC. parameters: - name: upc in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string responses: 200: description: The UPC is available for use. examples: application/json: is_orchard_upc: true /upc/provision: post: tags: - upc description: Retrieve a provisioned UPC using the UPC Provisioner. Update the status of the UPC to 'used' when {'mark_used':true} param passed in. parameters: - name: mark_used in: body required: false description: | Boolean value for mark_used. example: ```json { 'mark_used': True } ``` responses: 200: description: | HTTP 200 OK. --------------- JSON object containing retrieved upc headers: Correlation-Id: description: UUID to correlate logs (echoes back correlation_id from request header). type: string examples: application/json: upc: "123456789012" 404: description: 404 Not Found body: application/json: example: | { "code": "not_found_error", "message": null } 500: description: 500 Not Found body: application/json: example 1: | { "code": "internal_error", "message": "Unable to retrieve UPC" } example 2: | { "code": "failed_upc_status_update", "message": "The UPC status was not updated to used" } /public/languages: get: tags: - language description: Get all languages for localizations sorted alphabetically. Does not require grass session in query string. parameters: - name: Correlation-Id description: UUID in: header required: false type: string responses: 200: description: | HTTP 200 OK. ------------ JSON object representing immutable localization information from itunes_languages table. headers: Correlation-Id: description: UUID to correlate logs (echoes back correlation_id from request header). type: string examples: application/json: items: - id: 1 code: af name: Afrikaans meta_language_code: AFR - id: 2 code: ar name: Arabic meta_language_code: AFR - id: 3 code: bg name: Bulgarian meta_language_code: BUL pagination: type: standard offset: 0 limit: 100 total_records: 3 /vendor/{vendor_id}/upcs: post: tags: - vendor description: Verify a product is owned by a vendor. parameters: - name: vendor_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false - name: upcs in: body required: true description: | List of UPC(s). example: ```json { "upcs": [123456, 234234] } ``` responses: 200: description: | HTTP 200 OK --------------- All upc(s) belong to vendor 123 403: description: 403 Forbidden body: application/json: example: | { "code": "authorization_error", "message": "User is forbidden" } 400: description: 400 Bad Request body: application/json: example 1: | { "code": "bad_grass_request_error", "message": "Incomplete Grass Headers" } example 2: | { "code": "bad_request", "message": "invalid_data" } 404: description: 404 Not Found body: application/json: example 1: | { "code": "not_found_error", "message": "upc(s) 12313214 do not belong to vendor 123" } /subaccount/{subaccount_id}/upcs: post: tags: - subaccount description: Verify a product is owned by a subaccount. parameters: - name: subaccount_id in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Grass-Account-Type in: header description: Grass account type. enum: ["vendor", "subaccount"] type: string required: false - name: Grass-Account-Id in: header description: Grass account id. pattern: ^\d+$ type: string required: false - name: upcs in: body required: true description: | List of UPC(s). example: ```json { "upcs": [123456, 234234] } ``` responses: 200: description: | HTTP 200 OK --------------- All upc(s) belong to subaccount 123 403: description: 403 Forbidden body: application/json: example: | { "code": "authorization_error", "message": "User is forbidden" } 400: description: 400 Bad Request body: application/json: example 1: | { "code": "bad_grass_request_error", "message": "Incomplete Grass Headers" } example 2: | { "code": "bad_request", "message": "invalid_data" } 404: description: 404 Not Found body: application/json: example 1: | { "code": "not_found_error", "message": "upc(s) 123456 do not belong to subaccount 123" } /sound-recording/{isrc}/products: get: description: Get the products for an ISRC. parameters: - name: isrc in: path required: true type: string - name: Correlation-Id description: UUID in: header required: false type: string - name: Orchard-User-Id in: header description: Orchard User Id type: string required: true responses: 200: description: | HTTP 200 OK --------------- All products where the isrc is used body: application/json: example: | { "items": [ { "product_id": 2574915, "distribution_format_id": 1, "project_id": 4120588, "product_type_id": 1, "upc": 193483482378, "context_type": "digital", "vendor_id": 21989, "subaccount_id": 19713, "release_date": null, "status": "in_content", "product_name": "Godfrey", "deletions": "N", "not_for_distribution": "N" } ] } 403: description: 403 Forbidden body: application/json: example: | { "code": "authorization_error", "message": "User is forbidden" } 400: description: 400 Bad Request body: application/json: example 1: | { "code": "bad_grass_request_error", "message": "Incomplete Grass Headers" } example 2: | { "code": "bad_request", "message": "invalid_data" } 404: description: 404 Not Found body: application/json: example 1: | { "code": "not_found_error", "message": "no products found for isrc ddd" } /release-artist/{release_artist_id}/product: get: description: Get the product for an release_artist_id. parameters: - name: release_artist_id in: path required: true type: integer - name: Correlation-Id description: UUID in: header required: false type: string - name: Orchard-User-Id in: header description: Orchard User Id type: string required: true responses: 200: description: | HTTP 200 OK --------------- Product using release_artist with given release_artist_id body: application/json: example: | { "product_id": 2574915, "distribution_format_id": 1, "project_id": 4120588, "product_type_id": 1, "upc": 193483482378, "context_type": "digital", "vendor_id": 21989, "subaccount_id": 19713, "release_date": null, "status": "in_content", "product_name": "Godfrey", "deletions": "N" } 403: description: 403 Forbidden body: application/json: example: | { "code": "authorization_error", "message": "User is forbidden" } 400: description: 400 Bad Request body: application/json: example 1: | { "code": "bad_grass_request_error", "message": "Incomplete Grass Headers" } example 2: | { "code": "bad_request", "message": "invalid_data" } 404: description: 404 Not Found body: application/json: example 1: | { "code": "not_found_error", "message": "release artist not found by given release_artist_id 12345" } definitions: CopyProductPayload: type: object properties: product_code: type: string distribution_format_id: type: integer units_per_set: type: integer value_add_id: type: integer required: - product_code PostProductLanguagePayload: type: object properties: product_name: type: string description: Required product_name short_synopsis: type: string long_synopsis: type: string required: - product_name PutTrackLocalizationPayload: type: object properties: track_name: type: string description: Track name mandatory. version: type: string description: Track version key is mandatory. artists: type: object description: 'key-value pair of artist id: translated artist name.' required: - track_name - version PutBulkTrackLocalizationsPayload: type: object properties: items: description: List of all track localization items. type: array items: type: object properties: tuid: type: integer description: Track unique Id. language_id: type: integer description: Language id. track_name: type: string description: Localized track name. version: type: string description: Localized track version. artists: type: object description: 'key-value pair of artist_id: translated artist_name.' required: - tuid - language_id - track_name - version required: - items PhoneticTranslationsPayload: type: object properties: release_id: type: integer example: 12345 field_name: type: string example: "title" language_id: type: integer example: 1 phonetic_translation: type: string example: "phonetic translation for title" ProductDocumentResponse: type: object properties: release_id: type: integer example: 12345 display_upc: type: string example: 0123456789111 upc: type: integer example: 0123456789111 release_name: type: string example: Product Title imprint: type: string example: Label Name release_date: type: string example: "2018-01-01" release_year: type: string example: 2018 release_month: type: string example: 1 sale_start_date: type: string example: "2018-02-01" format: type: string example: Full Length description: releases.format c_line: type: string example: 2018 Record Label deletions: type: string example: "N" description: "Y/N" product_type_id: type: integer example: 1 product_type: type: string example: Music vendor_catalog_number: type: string example: 123ABC display: type: string example: Y description: "IF(vendor.label_identifier='Test','N',releases.display)" release_status: type: string example: label_processing track_list: type: array items: type: string example: ["track 1", "track 2", "track 3"] isrc_list: type: array items: type: string example: ["11111111", "11111112", "11111113"] track_type: type: array items: type: string example: ["music", "music", "music"] artist_name: type: string example: Artist 555 artist_description: type: string example: Just ok, bad at guitar artist_url: type: string example: https://artist555.com artist_url_myspace: type: string example: https://myspace.com/artist555 label: type: string example: Record Label description: vendor.company vendor_id: type: integer example: 77777 subaccount_id: type: integer example: 88888 vendor_owner: type: string example: Johnny Setbreak description: vendor.owner genre: type: string example: Blues description: "IF(releases.product_type_id=3, film_genre.genre, IF(releases.product_type_id=2, subgenre.name, genre.genre))" genre_id: type: integer example: 123 description: "IF(releases.product_type_id=1, genre.genre_id, NULL))" subgenre: type: string example: Acoustic Blues description: "IF(releases.product_type_id=1, subgenre.name, NULL)" subgenre_id: type: integer example: 123 description: "IF(releases.product_type_id=1, subgenre.orchard_id, NULL)" episode: type: string example: null description: | IF(releases.product_type_id=2, CONCAT('S:', releases.season, ", Ep:", releases.episode), NULL) featured: type: string example: Y description: | IF(FIND_IN_SET('a', GROUP_CONCAT(DISTINCT mkt_priority.priority)) > 0, 'Y', 'N') configuration: type: string example: 12 x 7" Vinyl description: | IF(distribution_format.context_type='physical', product_physical.display_configuration, distribution_format_media.name) product_configuration: type: string example: Physical Audio description: | IF(releases.product_type_id=3, 'Movie', IF(releases.product_type_id=2, 'TV Show', IF(releases.product_type_id=1 AND releases.distribution_format_id=1, 'Digital Audio', IF(distribution_format.context_type='physical', 'Physical Audio', IF(releases.product_type_id=1 AND releases.distribution_format_id=57, 'Music Video', 'Other'))))) product_code: type: string example: 12345577 description: releases.product_code project_id: type: string example: 555 version: type: string example: Apple Version description: releases.version delivered_version: type: string example: Live at Wembley description: releases.delivered_version context_type: description: The context_type of the product example: digital type: string