swagger: '2.0' info: description: | The API specs for ows-reporting. version: 1.0.0 title: OWS Reporting host: qa-ows-reporting.theorchard.io tags: - name: health description: Health endpoints. - name: mode description: Mode Report API based endpoints. - name: reporting description: Direct DB query endpoints schemes: - https paths: /hello/: get: tags: - health description: Check the health of the application. responses: '200': description: 200 OK examples: application/json: status: ok '/space/{space_name}/report/{report_name}': get: tags: - mode summary: Get details of a specific report by name. description: | Get the details of a specific report by name. E.g. the `product_view` report within the `workstation_physical` space. produces: - application/json parameters: - in: path name: space_name type: string required: true description: The name of the space (without the environment prefix) e.g. `workstation_physical` - in: path name: report_name type: string required: true description: The name of the report e.g. `product_view` responses: '200': description: HTTP Ok. examples: application/json: token: ab0ea2afedc7 id: 533579 name: product_view description: '' more: ... '/report/{report_token}/embed': post: tags: - mode summary: Get the signed embed src for a report with given parameters. description: | HTTP Ok. Get the generated signed embed src for an inline report with given parameters. consumes: - application/json produces: - application/json parameters: - in: path name: report_token type: string required: true description: The Mode report id (token) to run - in: header name: Grass-Account-Id description: The Grass account id. type: string - in: header name: Grass-Account-Type description: The Grass account type. pattern: ^(subaccount)$|^(vendor)$ type: string - in: body name: params schema: type: object example: vendor_id: 7123 subaccount_id: 88876 limit: 100 description: JSON object with parameters that are specified in the report definition responses: '200': description: | HTTP Ok. The embed src was generate successfully. schema: type: object properties: signed_embed_src: type: string examples: application/json: signed_embed_src: 'https://modeanalytics.com/theorchard/reports/7e5241b78972/embed?access_key=0dae807cb24330c9142f909a&max_age=0¶m_vendor_id=25170¶m_limit=250×tamp=1498595376&signature=88a7291851d8495d6ad935bb3f9331a945367a321a4859172a89c92ff23844b9' '400': description: | HTTP Bad Request. Most likely missing or incomplete body parameters. '403': description: | HTTP Forbidden. The subaccount_id or vendor_id passed in does not belong to the user context from the Grass headers. '404': description: | HTTP Not Found. The report id was not found. '/report/{report_token}/run': post: tags: - mode summary: Initiate the generation of a new report run. Returns the report_run_token for querying the status/generating a csv of the report. produces: - application/json parameters: - in: path name: report_token type: string required: true description: The Mode report id (token) to run - in: header name: Grass-Account-Id description: The Grass account id. type: string - in: header name: Grass-Account-Type description: The Grass account type. pattern: ^(subaccount)$|^(vendor)$ type: string - in: body name: params schema: type: object example: artist: 'The Three Tacos' limit: 100 description: JSON object with parameters that are specified in the report definition responses: '200': description: |- HTTP Ok. The report run was successfully initiated and will return a `report_run_token` schema: type: object properties: run_token: type: string examples: application/json: run_token: c82549328067 '403': description: | HTTP Forbidden. This report run does not belong to this vendor. This can be inferred from the `parameters` of the report run, which should contain a vendor_id or subaccount_id that belongs to the user context from the Grass headers. '404': description: |- HTTP Not Found. The report was not found. '/report/{report_token}/report_run/{report_run_token}': get: tags: - mode summary: 'Check on the status of a report run. If the report run has completed, respond with the reporting data' description: | Check on the status of a report run. If the report run has completed, respond with the reporting data. produces: - application/json parameters: - in: path name: report_token type: string required: true description: The Mode report id (token) to run - in: path name: report_run_token type: string required: true description: The Mode report_run_token for the report_token that we are inquiring about - in: header name: Grass-Account-Id description: The Grass account id. type: string - in: header name: Grass-Account-Type description: The Grass account type. pattern: ^(subaccount)$|^(vendor)$ type: string responses: '200': description: | HTTP Ok. The report has completed, send back the report data. '204': description: | HTTP No Content. The report run has not completed execution yet, try again later. '403': description: | HTTP Forbidden. This report run does not belong to this vendor. This can be inferred from the `parameters` of the report run, which should contain a vendor_id or subaccount_id that belongs to the user context from the Grass headers. '404': description: |- HTTP Not Found. The report or report run was not found. '/report/presets': get: tags: - reporting description: Get all report presets for a vendor or subaccount requesting through Grass. produces: - application/json parameters: - in: header name: Grass-Account-Type description: Orchard account type from Grass. type: string pattern: ^vendor|subaccount$ - in: header name: Grass-Account-Id description: Orchard account id from Grass. type: string pattern: ^\d+$ - in: header name: Orchard-User-Id description: Orchard user id from Grass. type: string pattern: ^\d+$ responses: '200': description: A list of report presets. schema: type: object properties: items: type: array items: type: object required: - id - name - report_id - params - datetime_created - is_orchard_preset properties: id: type: integer name: type: string report_id: type: string params: type: object datetime_created: type: date-time is_orchard_preset: type: boolean '400': description: Grass headers not present. '/report/{report_name}': post: tags: - reporting summary: Use $reportName like `workstation_physical_product_view_UK` and fetch it's data using possible JSON body parameters. consumes: - application/json produces: - application/json parameters: - in: path name: report_name type: string required: true description: A report name that maps to a report query. - in: header name: Grass-Account-Id description: | The Grass account id. Required state dictated by report configuration. type: string - in: header name: Grass-Account-Type description: | The Grass account type. Required state dictated by report configuration. pattern: ^(subaccount)$|^(vendor)$ type: string - in: body name: params schema: type: object example: artist: 'The Three Tacos' limit: 100 description: JSON object with parameters that are specified in each report definition responses: '200': description: |- HTTP Ok. Return the data. schema: $ref: "#/definitions/ReportDataResponse" examples: application/json: columns: - Artist - Product Name content: - Artist: Artist 1 Product Name: Product 1 - Artist: Artist 2 Product Name: Product 2 '403': description: | HTTP Forbidden. The vendor_id requested in the parameters does not match Grass headers, for example. '404': description: |- HTTP Not Found. The report was not found. '/report/{report_name}/filters': post: tags: - reporting summary: Use $reportName like `workstation_physical_product_view_UK` and fetch all filters options for that report. description: Use $reportName like `workstation_physical_product_view_UK` and fetch all filters options for that report. Filters do not expect to be limited, so that parameter should effectively be ignored if sent. consumes: - application/json produces: - application/json parameters: - in: path name: report_name type: string required: true description: The report for which you would like to fetch filters. - in: header name: Grass-Account-Id description: | The Grass account id. Required state dictated by report configuration. type: string - in: header name: Grass-Account-Type description: | The Grass account type. Required state dictated by report configuration. type: string - in: body name: params schema: type: object example: artist: 'The Three Tacos' description: JSON object with parameters as properties. responses: '200': description: |- HTTP Ok. Return the filter options data. schema: $ref: "#/definitions/ReportFilterOptions" examples: application/json: - Artist: - Artist 1 - Artist 2 - Artist 3 - Artist 4 - Product Name: - Product 1 - Product 2 - Product 3 - Product 4 '403': description: | HTTP Forbidden. The vendor_id requested in the parameters does not match Grass headers, for example. '404': description: |- HTTP Not Found. The report was not found. '/product/{local_product_cd}/sales_by_month': get: tags: - reporting - product details summary: Endpoint to hit PHYSICAL_PRODUCT_SALES_BY_MONTH_VIEW with a product identifier and territory. description: Use `local_product_cd` and territory to display a product level report. consumes: - application/json produces: - application/json parameters: - in: path name: local_product_cd type: string required: true description: The local product code to fetch a product report by. - in: body name: territory schema: type: string example: territory: 'CA' responses: '200': description: |- HTTP Ok. Return data associated with the product report. schema: $ref: "#/definitions/SingleProductViewSalesSalesByMonth" examples: application/json: columns: - time_frame: 'November 2016' - ship_number: 20 - return_number: 2 - net_number: 3 - ship_amount: 10.00 - return_amount: 20.00 - net_amount: 30.00 - percent_returns: 10 '/product/{local_product_cd}/sales_rtd': get: tags: - reporting - product details summary: Endpoint to hit PHYSICAL_PRODUCT_SALES_RTD_VIEW with a product identifier and territory. description: Use `local_product_cd` and territory to display a product level report. consumes: - application/json produces: - application/json parameters: - in: path name: local_product_cd type: string required: true description: The local product code to fetch a product report by. - in: body name: territory schema: type: string example: territory: 'CA' responses: '200': description: |- HTTP Ok. Return data associated with the product report. schema: $ref: "#/definitions/SingleProductViewSalesRtd" examples: application/json: columns: - time_frame: 'Day 1' - ship_number: 20 - return_number: 2 - net_number: 3 - ship_amount: 10.00 - return_amount: 20.00 - net_amount: 30.00 - percent_returns: 10 definitions: ReportDataResponse: type: object properties: columns: type: array items: type: string example: - Artist - Product Name content: type: array items: type: object example: - Artist: Artist 1 Product Name: Product Name 1 - Artist: Artist 2 Product Name: Product Name 2 required: - columns - content ReportFilterOptions: type: array items: type: object properties: options: type: array items: type: string example: - Artist 1 - Artist 2 - Artist 3 additionalProperties: type: string example: 'Artist' required: - options SingleProductViewSalesRtd: type: array items: type: object properties: columns: type: array items: type: string example: - time_frame: 'Day 1' - ship_number: 20 - return_number: 2 - net_number: 3 - ship_amount: 10.00 - return_amount: 20.00 - net_amount: 30.00 - percent_returns: 10 SingleProductViewSalesSalesByMonth: type: array items: type: object properties: columns: type: array items: type: string example: - time_frame: 'November 2017' - ship_number: 20 - return_number: 2 - net_number: 3 - ship_amount: 10.00 - return_amount: 20.00 - net_amount: 30.00 - percent_returns: 10