From 8d0862598f6a829ebc0a983151c75b04b37170d2 Mon Sep 17 00:00:00 2001 From: Miguel Mendoza Date: Mon, 6 May 2024 19:07:04 -0700 Subject: [PATCH] misc: remove oas3-to-oas2 command --- cmd/apigee-go-gen/transform/cmd.go | 2 - .../transform/oas3-to-oas2/cmd.go | 42 - docs/transform/commands/oas3-to-oas2.md | 59 - docs/transform/index.md | 2 - pkg/utils/openapi3_test.go | 105 - pkg/utils/testdata/oas3-to-oas2/.gitignore | 16 - .../testdata/oas3-to-oas2/npr/exp-oas2.json | 2016 ----------------- .../testdata/oas3-to-oas2/npr/exp-oas2.yaml | 1345 ----------- 8 files changed, 3587 deletions(-) delete mode 100644 cmd/apigee-go-gen/transform/oas3-to-oas2/cmd.go delete mode 100644 docs/transform/commands/oas3-to-oas2.md delete mode 100644 pkg/utils/openapi3_test.go delete mode 100644 pkg/utils/testdata/oas3-to-oas2/.gitignore delete mode 100644 pkg/utils/testdata/oas3-to-oas2/npr/exp-oas2.json delete mode 100644 pkg/utils/testdata/oas3-to-oas2/npr/exp-oas2.yaml diff --git a/cmd/apigee-go-gen/transform/cmd.go b/cmd/apigee-go-gen/transform/cmd.go index 017c416..1e09b7c 100644 --- a/cmd/apigee-go-gen/transform/cmd.go +++ b/cmd/apigee-go-gen/transform/cmd.go @@ -19,7 +19,6 @@ import ( apiproxy_to_yaml "github.com/apigee/apigee-go-gen/cmd/apigee-go-gen/transform/apiproxy-to-yaml" json_to_yaml "github.com/apigee/apigee-go-gen/cmd/apigee-go-gen/transform/json-to-yaml" oas2_to_oas3 "github.com/apigee/apigee-go-gen/cmd/apigee-go-gen/transform/oas2-to-oas3" - oas3_to_oas2 "github.com/apigee/apigee-go-gen/cmd/apigee-go-gen/transform/oas3-to-oas2" resolve_refs "github.com/apigee/apigee-go-gen/cmd/apigee-go-gen/transform/resolve-refs" sharedflow_to_yaml "github.com/apigee/apigee-go-gen/cmd/apigee-go-gen/transform/sharedflow-to-yaml" xml_to_yaml "github.com/apigee/apigee-go-gen/cmd/apigee-go-gen/transform/xml-to-yaml" @@ -43,7 +42,6 @@ func init() { Cmd.AddCommand(sharedflow_to_yaml.Cmd) Cmd.AddCommand(yaml_to_sharedflow.Cmd) Cmd.AddCommand(oas2_to_oas3.Cmd) - Cmd.AddCommand(oas3_to_oas2.Cmd) Cmd.AddCommand(resolve_refs.Cmd) Cmd.AddCommand(json_to_yaml.Cmd) Cmd.AddCommand(yaml_to_json.Cmd) diff --git a/cmd/apigee-go-gen/transform/oas3-to-oas2/cmd.go b/cmd/apigee-go-gen/transform/oas3-to-oas2/cmd.go deleted file mode 100644 index c2c26bd..0000000 --- a/cmd/apigee-go-gen/transform/oas3-to-oas2/cmd.go +++ /dev/null @@ -1,42 +0,0 @@ -// Copyright 2024 Google LLC -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -package oas3_to_oas2 - -import ( - "github.com/apigee/apigee-go-gen/pkg/flags" - "github.com/apigee/apigee-go-gen/pkg/utils" - "github.com/spf13/cobra" -) - -var input flags.String -var output flags.String -var allowCycles = flags.NewBool(false) - -var Cmd = &cobra.Command{ - Use: "oas3-to-oas2", - Short: "Transforms the input OpenAPI 3 spec into OpenAPI 2 spec", - RunE: func(cmd *cobra.Command, args []string) error { - return utils.OAS3FileToOAS2File(string(input), string(output), bool(allowCycles)) - }, -} - -func init() { - - Cmd.Flags().SortFlags = false - Cmd.Flags().VarP(&input, "input", "i", "path to input file, or omit to use stdin") - Cmd.Flags().VarP(&output, "output", "o", "path to output file, or omit to use stdout") - Cmd.Flags().VarP(&allowCycles, "allow-cycles", "c", "allow cyclic JSONRefs") - -} diff --git a/docs/transform/commands/oas3-to-oas2.md b/docs/transform/commands/oas3-to-oas2.md deleted file mode 100644 index 2bcd66a..0000000 --- a/docs/transform/commands/oas3-to-oas2.md +++ /dev/null @@ -1,59 +0,0 @@ -# OpenAPI 3 to OpenAPI 2 - - -This command takes an OpenAPI 3 spec and converts into an OpenAPI 2 spec (also known as Swagger). - -## Usage - -The `oas3-to-oas2` command takes two parameters `-input` and `-output` - -* `--input` is the OpenAPI 3 document to transform (either as JSON or YAML) - -* `--output` is the OpenAPI 2 document to be created (either as JSON or YAML) - -* `--output` full path is created if it does not exist (like `mkdir -p`) - -* `--allow-cycles` external cyclic JSONRefs are replaced with empty placeholders `{}` - -> You may omit the `--input` or `--output` flags to read or write from stdin or stdout - -!!! Note - Under the hood, this command uses the [kin-openapi](https://pkg.go.dev/github.com/getkin/kin-openapi) Go library to do the conversion - - -### Examples -Below are a few examples for using the `oas3-to-oas2` command. - -#### From files -Reading and writing to files explicitly -```shell -apigee-go-gen transform oas3-to-oas2 \ - --input ./examples/specs/oas3/npr.yaml \ - --output ./out/specs/oas2/npr.yaml -``` - -#### From stdin / stdout -* Reading from stdin (from a file) and writing to stdout -```shell -apigee-go-gen transform oas3-to-oas2 < ./examples/specs/oas3/npr.yaml -``` - -#### From a process -Reading from stdin (piped from another process) and writing to stdout -```shell -cat ./examples/specs/oas3/npr.yaml | apigee-go-gen transform oas3-to-oas2 -``` \ No newline at end of file diff --git a/docs/transform/index.md b/docs/transform/index.md index 8a38928..cc197e3 100644 --- a/docs/transform/index.md +++ b/docs/transform/index.md @@ -32,9 +32,7 @@ The `apigee-go-gen` includes the following set of `transform` commands to help y * [sharedflow-to-yaml](./commands/sharedflow-to-yaml.md) - Transforms an Apigee API shared flow bundle to a YAML doc * [yaml-to-sharedflow](./commands/yaml-to-sharedflow.md) - Transforms a YAML doc to an Apigee shared flow bundle - * [oas2-to-oas3](./commands/oas2-to-oas3.md) - Transforms an OpenAPI 2 spec (also known as Swagger) into OpenAPI 3 -* [oas3-to-oas2](./commands/oas3-to-oas2.md) - Transforms an OpenAPI 3 spec into OpenAPI 2 (also known as Swagger) * [resolve-refs](./commands/resolve-refs.md) - Replace external $refs (JSONRefs) in input YAML or JSON doc with actual values diff --git a/pkg/utils/openapi3_test.go b/pkg/utils/openapi3_test.go deleted file mode 100644 index 7b06b51..0000000 --- a/pkg/utils/openapi3_test.go +++ /dev/null @@ -1,105 +0,0 @@ -// Copyright 2024 Google LLC -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -package utils - -import ( - "fmt" - "github.com/stretchr/testify/require" - "os" - "path/filepath" - "testing" -) - -func TestOpenAPI3FileToOpenAPI2File(t *testing.T) { - - tests := []struct { - name string - dir string - inputFile string - expectedFile string - allowCycles bool - wantErr error - }{ - { - - "npr OAS3(JSON) to OAS2(JSON)", - "npr", - "oas3.json", - "oas2.json", - false, - nil, - }, - { - "npr OAS3(JSON) to OAS2(YAML)", - "npr", - "oas3.json", - "oas2.yaml", - false, - nil, - }, - { - "npr OAS3(YAML) to OAS2(YAML)", - "npr", - "oas3.yaml", - "oas2.yaml", - false, - nil, - }, - { - "npr OAS3(YAML) to OAS2(JSON)", - "npr", - "oas3.yaml", - "oas2.json", - false, - nil, - }, - } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - ttSrcDir := filepath.Join("testdata", "specs", "oas3", tt.dir) - ttDstDir := filepath.Join("testdata", "oas3-to-oas2", tt.dir) - - inputFile := filepath.Join(ttSrcDir, tt.inputFile) - outputFile := filepath.Join(ttDstDir, fmt.Sprintf("out-%s", tt.expectedFile)) - expectedFile := filepath.Join(ttDstDir, fmt.Sprintf("exp-%s", tt.expectedFile)) - - var err error - err = os.RemoveAll(outputFile) - require.NoError(t, err) - - err = OAS3FileToOAS2File(inputFile, outputFile, tt.allowCycles) - if tt.wantErr != nil { - require.EqualError(t, tt.wantErr, err.Error()) - return - } - - require.NoError(t, err) - - outputBytes := MustReadFileBytes(outputFile) - expectedBytes := MustReadFileBytes(expectedFile) - - if filepath.Ext(expectedFile) == ".json" { - require.JSONEq(t, string(expectedBytes), string(outputBytes)) - } else if filepath.Ext(expectedFile) == ".yaml" { - outputBytes = RemoveYAMLComments(outputBytes) - expectedBytes = RemoveYAMLComments(expectedBytes) - require.YAMLEq(t, string(expectedBytes), string(outputBytes)) - } else { - t.Error("unknown output format in testcase") - } - - }) - } -} diff --git a/pkg/utils/testdata/oas3-to-oas2/.gitignore b/pkg/utils/testdata/oas3-to-oas2/.gitignore deleted file mode 100644 index 1a27edf..0000000 --- a/pkg/utils/testdata/oas3-to-oas2/.gitignore +++ /dev/null @@ -1,16 +0,0 @@ -# Copyright 2024 Google LLC -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http:#www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -**/out-*.yaml -**/out-*.json \ No newline at end of file diff --git a/pkg/utils/testdata/oas3-to-oas2/npr/exp-oas2.json b/pkg/utils/testdata/oas3-to-oas2/npr/exp-oas2.json deleted file mode 100644 index a2f5d9c..0000000 --- a/pkg/utils/testdata/oas3-to-oas2/npr/exp-oas2.json +++ /dev/null @@ -1,2016 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "contact": { - "email": "NPROneEnterprise@npr.org", - "name": "NPR One Enterprise Team", - "url": "https://dev.npr.org" - }, - "description": "Audio recommendations tailored to a user's preferences", - "termsOfService": "https://dev.npr.org/guide/prerequisites/terms-of-use", - "title": "NPR Listening Service", - "version": "2" - }, - "host": "listening.api.npr.org", - "schemes": [ - "https" - ], - "externalDocs": { - "description": "Learn more at the NPR One Developer Center", - "url": "https://dev.npr.org/guide/services/listening" - }, - "tags": [ - { - "description": "Audio recommendations tailored to a user's preferences", - "name": "listening" - } - ], - "paths": { - "/v2/aggregation/{aggId}/recommendations": { - "get": { - "description": "This endpoint provides a list of recent audio items associated with the aggregation along with metadata about the aggregation.", - "operationId": "getAggRecommendations", - "parameters": [ - { - "$ref": "#/parameters/Authorization" - }, - { - "description": "ID of an aggregation such as a program or podcast. If the specified ID is a program that publishes rundowns, the latest rundown will be returned.", - "format": "int64", - "in": "path", - "name": "aggId", - "required": true, - "type": "integer" - }, - { - "default": 0, - "description": "The result to start with. Allows paging through the episodes of a podcast or program, with the default, `startNum=0`, being the most recent episode. Ignored for programs that publish a rundown.", - "format": "int32", - "in": "query", - "name": "startNum", - "type": "integer" - } - ], - "responses": { - "200": { - "description": "A list of audio items from the specified aggregation", - "headers": { - "X-RateLimit-Limit": { - "description": "The number of allowed requests in the current period", - "type": "integer" - }, - "X-RateLimit-Remaining": { - "description": "The number of remaining requests in the current period", - "type": "integer" - }, - "X-RateLimit-Reset": { - "description": "The number of seconds left in the current period", - "type": "integer" - } - } - }, - "401": { - "$ref": "#/responses/401WithDocument" - }, - "404": { - "$ref": "#/responses/404WithDocument" - }, - "429": { - "$ref": "#/responses/429WithDocument" - }, - "500": { - "$ref": "#/responses/500WithDocument" - }, - "503": { - "$ref": "#/responses/503WithDocument" - } - }, - "security": [ - { - "oauth2": [ - "listening.readonly" - ] - } - ], - "summary": "Get a set of recommendations for an aggregation independent of the user's listening history", - "tags": [ - "listening" - ] - } - }, - "/v2/channels": { - "get": { - "description": "These channels allow the user to specify a focus for the content returned in the recommendations endpoint.", - "operationId": "getChannels", - "parameters": [ - { - "$ref": "#/parameters/Authorization" - }, - { - "default": false, - "description": "If set to `true`, this call will return only channels that should be shown in the client's `Explore` view", - "in": "query", - "name": "exploreOnly", - "type": "boolean" - } - ], - "responses": { - "200": { - "description": "A list of channels", - "headers": { - "X-RateLimit-Limit": { - "description": "The number of allowed requests in the current period", - "type": "integer" - }, - "X-RateLimit-Remaining": { - "description": "The number of remaining requests in the current period", - "type": "integer" - }, - "X-RateLimit-Reset": { - "description": "The number of seconds left in the current period", - "type": "integer" - } - } - }, - "401": { - "$ref": "#/responses/401WithDocument" - }, - "429": { - "$ref": "#/responses/429WithDocument" - }, - "503": { - "$ref": "#/responses/503WithDocument" - } - }, - "security": [ - { - "oauth2": [ - "listening.readonly" - ] - } - ], - "summary": "Get the list of available channels", - "tags": [ - "listening" - ] - } - }, - "/v2/history": { - "get": { - "description": "This endpoint provides the list of recently-rated audio recommendations that the logged-in user has consumed. Some rated recommendations are filtered, such as sponsorship and donation.", - "operationId": "getHistory", - "parameters": [ - { - "$ref": "#/parameters/Authorization" - } - ], - "responses": { - "200": { - "$ref": "#/responses/ListeningSuccess" - }, - "401": { - "$ref": "#/responses/401WithDocument" - }, - "429": { - "$ref": "#/responses/429WithDocument" - }, - "500": { - "$ref": "#/responses/500WithDocument" - }, - "503": { - "$ref": "#/responses/503WithDocument" - } - }, - "security": [ - { - "oauth2": [ - "listening.readonly" - ] - } - ], - "summary": "Get recent ratings the logged-in user has submitted", - "tags": [ - "listening" - ] - } - }, - "/v2/organizations/{orgId}/categories/{category}/recommendations": { - "get": { - "description": "This endpoint provides a list of recommendations from a category of content from an organization.", - "operationId": "getOrganizationCategory", - "parameters": [ - { - "$ref": "#/parameters/Authorization" - }, - { - "default": "story", - "description": "One of the three categories of content - newscast, story, or podcast", - "enum": [ - "newscast", - "story", - "podcast" - ], - "in": "path", - "name": "category", - "required": true, - "type": "string" - }, - { - "description": "ID of an organization, such as an NPR One station", - "format": "int64", - "in": "path", - "name": "orgId", - "required": true, - "type": "integer" - } - ], - "responses": { - "200": { - "description": "A list of audio items from a category of content from an organization", - "headers": { - "X-RateLimit-Limit": { - "description": "The number of allowed requests in the current period", - "type": "integer" - }, - "X-RateLimit-Remaining": { - "description": "The number of remaining requests in the current period", - "type": "integer" - }, - "X-RateLimit-Reset": { - "description": "The number of seconds left in the current period", - "type": "integer" - } - } - }, - "401": { - "$ref": "#/responses/401WithDocument" - }, - "404": { - "$ref": "#/responses/404WithDocument" - }, - "429": { - "$ref": "#/responses/429WithDocument" - }, - "500": { - "$ref": "#/responses/500WithDocument" - }, - "503": { - "$ref": "#/responses/503WithDocument" - } - }, - "security": [ - { - "oauth2": [ - "listening.readonly" - ] - } - ], - "summary": "Get a list of recommendations from a category of content from an organization", - "tags": [ - "listening" - ] - } - }, - "/v2/organizations/{orgId}/recommendations": { - "get": { - "description": "This endpoint provides a variety of details about an organization including various lists of recent audio items.", - "operationId": "getOrganizationOverview", - "parameters": [ - { - "$ref": "#/parameters/Authorization" - }, - { - "description": "ID of an organization, such as an NPR One station", - "format": "int64", - "in": "path", - "name": "orgId", - "required": true, - "type": "integer" - } - ], - "responses": { - "200": { - "description": "A list of up to four different categories of audio items from a specific organization", - "headers": { - "X-RateLimit-Limit": { - "description": "The number of allowed requests in the current period", - "type": "integer" - }, - "X-RateLimit-Remaining": { - "description": "The number of remaining requests in the current period", - "type": "integer" - }, - "X-RateLimit-Reset": { - "description": "The number of seconds left in the current period", - "type": "integer" - } - } - }, - "401": { - "$ref": "#/responses/401WithDocument" - }, - "404": { - "$ref": "#/responses/404WithDocument" - }, - "429": { - "$ref": "#/responses/429WithDocument" - }, - "500": { - "$ref": "#/responses/500WithDocument" - }, - "503": { - "$ref": "#/responses/503WithDocument" - } - }, - "security": [ - { - "oauth2": [ - "listening.readonly" - ] - } - ], - "summary": "Get a variety of details about an organization including various lists of recent audio items", - "tags": [ - "listening" - ] - } - }, - "/v2/promo/recommendations": { - "get": { - "description": "Gets the most recently played promo for which the user has neither tapped through the promo or listened to the target story.", - "operationId": "getPromo", - "parameters": [ - { - "$ref": "#/parameters/Authorization" - } - ], - "responses": { - "200": { - "$ref": "#/responses/ListeningSuccess" - }, - "401": { - "$ref": "#/responses/401WithDocument" - }, - "429": { - "$ref": "#/responses/429WithDocument" - }, - "500": { - "$ref": "#/responses/500WithDocument" - }, - "503": { - "$ref": "#/responses/503WithDocument" - } - }, - "security": [ - { - "oauth2": [ - "listening.readonly" - ] - } - ], - "summary": "Retrieve the most recent promo audio heard by the logged-in user", - "tags": [ - "listening" - ] - } - }, - "/v2/ratings": { - "post": { - "description": "This endpoint is the main mechanism for providing feedback from the user to NPR about the recommendations that are obtained from `GET /listening/v2/recommendations`.\n\n A fully-populated link to this endpoint is returned with each individual recommendation and is located in the AudioItemDocument under the `links['recommendations']` object. The query parameters in this link should not be modified.\n Be sure to copy and send back the entire ratings object (RatingData), as new fields may be added to it in the future.\n\n This endpoint can return a blank JSON.doc or AudioItemDocument depending on the `recommend=true|false` parameter. The `recommend=true` flag allows this endpoint to both receive ratings and send back recommendations in the same call.", - "operationId": "postRating", - "parameters": [ - { - "$ref": "#/parameters/Authorization" - }, - { - "$ref": "#/parameters/X-Advertising-ID" - }, - { - "$ref": "#/parameters/channel" - }, - { - "default": true, - "description": "If set to `false`, this call will return a blank document; otherwise it will return a new recommendation object", - "in": "query", - "name": "recommend", - "type": "boolean" - } - ], - "responses": { - "200": { - "description": "If the `recommend` param was set to `true`, this returns a list of audio items; otherwise, a blank document is returned.", - "headers": { - "X-RateLimit-Limit": { - "description": "The number of allowed requests in the current period", - "type": "integer" - }, - "X-RateLimit-Remaining": { - "description": "The number of remaining requests in the current period", - "type": "integer" - }, - "X-RateLimit-Reset": { - "description": "The number of seconds left in the current period", - "type": "integer" - } - } - }, - "400": { - "$ref": "#/responses/400WithDocument" - }, - "401": { - "$ref": "#/responses/401WithDocument" - }, - "429": { - "$ref": "#/responses/429WithDocument" - }, - "500": { - "$ref": "#/responses/500WithDocument" - }, - "503": { - "$ref": "#/responses/503WithDocument" - } - }, - "security": [ - { - "oauth2": [ - "listening.write" - ] - } - ], - "summary": "Collect new ratings for media previously recommended to the logged-in user", - "tags": [ - "listening" - ] - } - }, - "/v2/recommendations": { - "get": { - "description": "This endpoint returns a list of audio recommendations. It is designed to be used for an initial list of recommendations, and then `POST /v2/ratings?recommend=true` should be used for subsequent requests for recommendations.\n\n A fully-populated link to the ratings endpoint is returned with each individual recommendation and is located in the AudioItemDocument under the `links['recommendations']` object. The query parameters in this link should not be modified.\n Be sure to copy and send back the entire ratings object (RatingData), as new fields may be added to it in the future.\n\n A 500 will be returned if there are no eligible remaining recommendations.", - "operationId": "getRecommendations", - "parameters": [ - { - "$ref": "#/parameters/Authorization" - }, - { - "$ref": "#/parameters/X-Advertising-ID" - }, - { - "$ref": "#/parameters/channel" - }, - { - "description": "The user received a push notification about this media; if provided, the service will add this recommendation to the top of the list", - "in": "query", - "name": "notifiedMediaId", - "type": "string" - }, - { - "description": "This media was shared directly with the user; if provided, the service will add this recommendation to the top of the list", - "in": "query", - "name": "sharedMediaId", - "type": "string" - } - ], - "responses": { - "200": { - "$ref": "#/responses/ListeningSuccess" - }, - "400": { - "$ref": "#/responses/400WithDocument" - }, - "401": { - "$ref": "#/responses/401WithDocument" - }, - "429": { - "$ref": "#/responses/429WithDocument" - }, - "500": { - "$ref": "#/responses/500WithDocument" - }, - "503": { - "$ref": "#/responses/503WithDocument" - } - }, - "security": [ - { - "oauth2": [ - "listening.readonly" - ] - } - ], - "summary": "Get a list of media for the logged-in user from NPR's recommendation engine", - "tags": [ - "listening" - ] - } - }, - "/v2/search/recommendations": { - "get": { - "description": "In the schema shown below, SearchItemDocument is not an actual type of returned object; the object returned by a search will be either an AggregationAudioItemListDocument or an AudioItemDocument.", - "operationId": "getSearchRecommendations", - "parameters": [ - { - "$ref": "#/parameters/Authorization" - }, - { - "description": "Search terms to search on; can include URL-encoded punctuation", - "in": "query", - "name": "searchTerms", - "required": true, - "type": "string" - } - ], - "responses": { - "200": { - "description": "A list of audio and aggregation items matching the search query", - "headers": { - "X-RateLimit-Limit": { - "description": "The number of allowed requests in the current period", - "type": "integer" - }, - "X-RateLimit-Remaining": { - "description": "The number of remaining requests in the current period", - "type": "integer" - }, - "X-RateLimit-Reset": { - "description": "The number of seconds left in the current period", - "type": "integer" - } - } - }, - "401": { - "$ref": "#/responses/401WithDocument" - }, - "429": { - "$ref": "#/responses/429WithDocument" - }, - "500": { - "$ref": "#/responses/500WithDocument" - }, - "503": { - "$ref": "#/responses/503WithDocument" - } - }, - "security": [ - { - "oauth2": [ - "listening.readonly" - ] - } - ], - "summary": "Get a list of recent audio and aggregation items associated with search terms", - "tags": [ - "listening" - ] - } - } - }, - "securityDefinitions": { - "oauth2": { - "authorizationUrl": "https://authorization.api.npr.org/v2/authorize", - "flow": "implicit", - "scopes": { - "identity.readonly": "See your personal information, such as your first name, last name, and favorite station.", - "identity.write": "Update your personal information, such as your favorite station(s) or program(s) you follow, on your behalf.", - "listening.readonly": "See your NPR One listening history and get audio recommendations.", - "listening.write": "Record that you have heard, marked as interesting, and/or skipped NPR One stories in order to personalize future audio recommendations.", - "localactivation": "Connect you with your local NPR member station for communication purposes." - }, - "type": "oauth2" - } - }, - "parameters": { - "Authorization": { - "description": "Your access token from the Authorization Service. Should start with `Bearer`, followed by a space, followed by the token.", - "in": "header", - "name": "Authorization", - "required": true, - "type": "string" - }, - "X-Advertising-ID": { - "description": "A device-specific advertising identifier, if possible. Apple's IDFA is an example.", - "in": "header", - "name": "X-Advertising-ID", - "type": "string" - }, - "channel": { - "default": "npr", - "description": "Determines the focus of the recommendations returned. Channel `npr` is recommended for most use cases.", - "enum": [ - "npr", - "followed", - "recommended", - "emailstories", - "emailprograms", - "lapsedusersemail", - "ongoing email", - "newscasts", - "shows" - ], - "in": "query", - "name": "channel", - "type": "string" - } - }, - "responses": { - "400WithDocument": { - "description": "A bad request; generally, one or more parameters passed in were incorrect or missing", - "headers": { - "X-RateLimit-Limit": { - "description": "The number of allowed requests in the current period", - "type": "integer" - }, - "X-RateLimit-Remaining": { - "description": "The number of remaining requests in the current period", - "type": "integer" - }, - "X-RateLimit-Reset": { - "description": "The number of seconds left in the current period", - "type": "integer" - } - } - }, - "401WithDocument": { - "description": "The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers." - }, - "404WithDocument": { - "description": "The resource with the requested ID could not be found, and the server was unable to complete the request.", - "headers": { - "X-RateLimit-Limit": { - "description": "The number of allowed requests in the current period", - "type": "integer" - }, - "X-RateLimit-Remaining": { - "description": "The number of remaining requests in the current period", - "type": "integer" - }, - "X-RateLimit-Reset": { - "description": "The number of seconds left in the current period", - "type": "integer" - } - } - }, - "429WithDocument": { - "description": "The client has exceeded the number of daily calls as per their rate limit. For now, this only applies to prototype applications and untrusted clients. Trusted clients will never be rate-limited, nor will any production apps.", - "headers": { - "X-RateLimit-Limit": { - "description": "The number of allowed requests in the current period", - "type": "integer" - }, - "X-RateLimit-Remaining": { - "description": "The number of remaining requests in the current period", - "type": "integer" - }, - "X-RateLimit-Reset": { - "description": "The number of seconds left in the current period", - "type": "integer" - } - } - }, - "500WithDocument": { - "description": "A server error", - "headers": { - "X-RateLimit-Limit": { - "description": "The number of allowed requests in the current period", - "type": "integer" - }, - "X-RateLimit-Remaining": { - "description": "The number of remaining requests in the current period", - "type": "integer" - }, - "X-RateLimit-Reset": { - "description": "The number of seconds left in the current period", - "type": "integer" - } - } - }, - "503WithDocument": { - "description": "The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.", - "headers": { - "Retry-After": { - "description": "The predicted time the system will be back up", - "format": "date-time", - "type": "string" - } - } - }, - "ListeningSuccess": { - "description": "A list of audio items (recommendations)", - "headers": { - "X-RateLimit-Limit": { - "description": "The number of allowed requests in the current period", - "type": "integer" - }, - "X-RateLimit-Remaining": { - "description": "The number of remaining requests in the current period", - "type": "integer" - }, - "X-RateLimit-Reset": { - "description": "The number of seconds left in the current period", - "type": "integer" - } - } - } - }, - "definitions": { - "AbstractCDocLink": { - "allOf": [ - { - "$ref": "#/definitions/AbstractLink" - }, - { - "properties": { - "content-type": { - "description": "The MIME type of the response of this link", - "type": "string" - } - }, - "required": [ - "content-type" - ], - "type": "object" - } - ] - }, - "AbstractLink": { - "properties": { - "href": { - "description": "The link to be followed", - "format": "uri", - "type": "string" - } - }, - "required": [ - "href" - ], - "type": "object" - }, - "Affiliation": { - "description": "A program (aggregation) that a given user has shown an affiliation with", - "properties": { - "daysSinceLastListen": { - "description": "The number of days since a user last listened to a story from this aggregation. Absent if user never listened to the aggregation.", - "format": "int32", - "type": "integer" - }, - "following": { - "default": false, - "description": "Whether or not the user is following the aggregation. When changing affiliation status, the client is expected to toggle this value and then send the entire object back.", - "type": "boolean" - }, - "href": { - "description": "A link to more details about the program from the NPR Story API", - "type": "string" - }, - "id": { - "description": "A unique identifier for the aggregation (program)", - "format": "int64", - "type": "integer" - }, - "notif_following": { - "description": "The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they follow.", - "items": { - "type": "string" - }, - "type": "array" - }, - "notif_rated": { - "description": "The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they have highly rated.", - "items": { - "type": "string" - }, - "type": "array" - }, - "rating": { - "description": "The user's average rating for this affiliation on a scale of 0-1. Absent if user never listened to the aggregation.", - "format": "float", - "type": "number" - }, - "title": { - "description": "The title for the aggregation (program)", - "type": "string" - } - }, - "required": [ - "id", - "href", - "following" - ], - "type": "object" - }, - "AggregationAudioItemListDocument": { - "allOf": [ - { - "$ref": "#/definitions/CollectionDocument" - }, - { - "properties": { - "attributes": { - "$ref": "#/definitions/AggregationData" - }, - "items": { - "description": "An array of Audio Items (recommendations)", - "items": { - "$ref": "#/definitions/AudioItemDocument" - }, - "type": "array" - }, - "links": { - "$ref": "#/definitions/AggregationLinks" - } - }, - "type": "object" - }, - { - "$ref": "#/definitions/AudioItemListDocument" - }, - { - "$ref": "#/definitions/AudioItemLinks" - } - ], - "description": "An array of audio recommendations with additional metadata about the aggregation they are associated with" - }, - "AggregationData": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemListDocument" - }, - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "affiliation": { - "description": "A unique identifier for the aggregation", - "type": "string" - }, - "affiliationMeta": { - "$ref": "#/definitions/Affiliation" - }, - "description": { - "description": "A short description or teaser", - "type": "string" - }, - "provider": { - "default": "NPR", - "description": "The producer of this aggregation", - "type": "string" - }, - "station": { - "default": "NPR", - "description": "Deprecated - clients should switch to use provider.", - "type": "string" - }, - "title": { - "description": "The title of this aggregation", - "type": "string" - }, - "type": { - "default": "aggregation", - "description": "The type of list returned; will always be `aggregation`; useful for parsing search results", - "enum": [ - "aggregation" - ], - "type": "string" - } - } - } - ], - "required": [ - "type", - "affiliation", - "title" - ], - "type": "object" - }, - "AggregationLinks": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemListDocument" - }, - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "binge": { - "description": "One or more links to more unrated / unheard recommendations from this aggregation", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - }, - "image": { - "description": "One or more links to an image, along with metadata for display", - "items": { - "$ref": "#/definitions/ImageLink" - }, - "type": "array" - }, - "more": { - "description": "One or more links to more episodes for the aggregation", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - }, - "web": { - "description": "One or more links to a web page for the item", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - } - } - } - ], - "type": "object" - }, - "AudioItemData": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "album": { - "description": "Album information associated with the media", - "type": "string" - }, - "artist": { - "description": "The artist associated with the media", - "type": "string" - }, - "audioTitle": { - "description": "For first-party client use only", - "type": "string" - }, - "bingeAggId": { - "description": "Indicates which aggregration ID this recommendation was binged from", - "type": "string" - }, - "button": { - "description": "The text contents of an action button displayed on the client", - "type": "string" - }, - "date": { - "description": "The publication date in ISO-8601 format", - "format": "date-time", - "type": "string" - }, - "description": { - "description": "A short description or teaser", - "type": "string" - }, - "duration": { - "description": "The length of the audio content in seconds", - "format": "int32", - "maximum": 9999, - "minimum": 0, - "type": "integer" - }, - "expires": { - "description": "The media's expiration date in ISO-8601 format", - "format": "date-time", - "type": "string" - }, - "geofence": { - "$ref": "#/definitions/Geofence" - }, - "inFlow": { - "description": "Indicates the likelihood of being within a flow, useful for stateful playback buttons", - "type": "boolean" - }, - "label": { - "description": "The record label associated with the media", - "type": "string" - }, - "organization": { - "$ref": "#/definitions/RecommendationOrganization" - }, - "primary": { - "description": "Whether the audio is the primary audio of the story to which it is associated", - "type": "boolean" - }, - "program": { - "description": "The program associated with this media", - "type": "string" - }, - "provider": { - "default": "NPR", - "description": "The name of the organization providing this media", - "type": "string" - }, - "rating": { - "$ref": "#/definitions/RatingData" - }, - "rationale": { - "description": "A short summary of why this content was recommended", - "type": "string" - }, - "skippable": { - "default": true, - "description": "Whether the client should allow this content to be skipped", - "type": "boolean" - }, - "slug": { - "description": "A tag or category for this media", - "type": "string" - }, - "song": { - "description": "The song title associated with the media", - "type": "string" - }, - "streamGuid": { - "description": "The full GUID of the live stream returned within the recommendation", - "type": "string" - }, - "title": { - "description": "The title of this media", - "type": "string" - }, - "type": { - "default": "audio", - "description": "Help determine how content is displayed; for more information, see \u003ca href='https://dev.npr.org/design/general-specifications/playing-audio/'\u003eour design guidelines\u003c/a\u003e", - "enum": [ - "audio", - "sponsorship", - "stationId", - "intro", - "donate", - "featureCardInformational", - "featureCardNotification", - "featureCardPromotion", - "featureCardExternalLink", - "featureCardAsyncRequest" - ], - "type": "string" - }, - "uid": { - "description": "The media ID (for use in ratings objects)", - "pattern": "^\\d{3,}:[\\w-]{5,}$", - "type": "string" - }, - "unavailableText": { - "description": "The text contents to be displayed on the client if no media URLs are available", - "type": "string" - } - } - } - ], - "required": [ - "type", - "uid", - "title", - "skippable", - "rationale", - "rating" - ], - "type": "object" - }, - "AudioItemDocument": { - "allOf": [ - { - "$ref": "#/definitions/CollectionDocument" - }, - { - "properties": { - "attributes": { - "$ref": "#/definitions/AudioItemData" - }, - "items": { - "description": "Not used", - "items": { - "type": "object" - }, - "type": "array" - }, - "links": { - "$ref": "#/definitions/AudioItemLinks" - } - }, - "type": "object" - }, - { - "$ref": "#/definitions/AudioItemLinks" - } - ] - }, - "AudioItemLinks": { - "properties": { - "action": { - "description": "One or more links to be trigged by user actions, usually when a button is clicked", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - }, - "audio": { - "description": "One or more links to audio files for the item", - "items": { - "$ref": "#/definitions/AudioLink" - }, - "type": "array" - }, - "binge": { - "description": "One or more links that start a flow-based experience focused on the aggregation", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - }, - "image": { - "description": "One or more links to an image, along with metadata for display", - "items": { - "$ref": "#/definitions/ImageLink" - }, - "type": "array" - }, - "onramps": { - "description": "One or more shareable links for the item", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - }, - "ratings": { - "description": "This is an alternate URL to use to POST the ratings JSON. Difference between this and 'recommendations' is that 'ratings' will NOT return back recommendations of audio to play next.", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - }, - "recommendations": { - "description": "This is the URL that should be POSTed with the ratings JSON when this audio starts to play", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - }, - "stream-metadata": { - "description": "Links that can be polled to retreive current program metadata for a given stream", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - }, - "up": { - "description": "One or more links to more details about the program or podcast with which this item is associated", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - }, - "web": { - "description": "One or more links to a web page for the item", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - } - }, - "type": "object" - }, - "AudioItemListDocument": { - "allOf": [ - { - "$ref": "#/definitions/CollectionDocument" - }, - { - "properties": { - "attributes": { - "description": "Not used", - "type": "object" - }, - "items": { - "description": "An array of Audio Items (recommendations)", - "items": { - "$ref": "#/definitions/AudioItemDocument" - }, - "type": "array" - }, - "links": { - "description": "Not used", - "type": "object" - } - }, - "type": "object" - } - ] - }, - "AudioLink": { - "allOf": [ - { - "$ref": "#/definitions/AbstractLink" - }, - { - "properties": { - "content-type": { - "default": "audio/aac", - "description": "The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes.", - "enum": [ - "audio/mp3", - "audio/aac", - "audio/3gp", - "application/vnd.apple.mpegurl", - "audio/x-ms-wax" - ], - "type": "string" - } - }, - "required": [ - "content-type" - ], - "type": "object" - } - ], - "description": "A link to audio files for the item" - }, - "AudioPlaylistData": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemListDocument" - }, - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "id": { - "description": "The globally unique identifier for the playlist.", - "type": "string" - }, - "title": { - "description": "The user-editable title of the playlist", - "type": "string" - }, - "uids": { - "description": "Individual content identifiers; see AudioItemDocument", - "items": { - "type": "string" - }, - "type": "array" - } - } - } - ], - "required": [ - "id", - "title", - "uids" - ], - "type": "object" - }, - "AudioPlaylistDocument": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemListDocument" - }, - { - "properties": { - "attributes": { - "$ref": "#/definitions/AudioPlaylistData" - }, - "items": { - "description": "An array of Audio Items (recommendations)", - "items": { - "$ref": "#/definitions/AudioItemDocument" - }, - "type": "array" - }, - "links": { - "$ref": "#/definitions/OtherLink" - } - }, - "type": "object" - }, - { - "$ref": "#/definitions/AudioItemListDocument" - }, - { - "$ref": "#/definitions/AudioItemLinks" - } - ] - }, - "Brand": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "band": { - "description": "The radio band for the organization if they are a station (AM or FM)", - "type": "string" - }, - "call": { - "description": "The call letter for the organization if they are a station", - "type": "string" - }, - "frequency": { - "description": "The radio frequency for the organization if they are a station", - "type": "string" - }, - "marketCity": { - "description": "The market city for the organization", - "type": "string" - }, - "marketState": { - "description": "The market state for the organization", - "type": "string" - }, - "name": { - "description": "The name of the organization", - "type": "string" - }, - "tagline": { - "description": "The tagline for the organization", - "type": "string" - } - } - } - ], - "description": "Branding information for the organization", - "required": [ - "name", - "call", - "marketCity" - ], - "type": "object" - }, - "CategoryData": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemListDocument" - }, - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "displayType": { - "description": "How clients should display this channel in the station profile view", - "enum": [ - "default", - "show", - "playable", - "newscast" - ], - "type": "string" - }, - "title": { - "description": "The title of this category", - "type": "string" - }, - "type": { - "default": "category", - "description": "The type of list returned; will always be `category`", - "type": "string" - } - } - } - ], - "required": [ - "type", - "title" - ], - "type": "object" - }, - "CategoryLinks": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemListDocument" - }, - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "more": { - "description": "One or more links to more episodes for the aggregation", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - } - } - } - ], - "type": "object" - }, - "ChannelData": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "description": { - "description": "A longer description of what this channel focuses on", - "type": "string" - }, - "displayType": { - "description": "How clients should display this channel in the explore view", - "enum": [ - "default", - "show", - "playable", - "newscast" - ], - "type": "string" - }, - "emptyText": { - "description": "Text for clients to display when the channel contains no recommendations", - "type": "string" - }, - "fullName": { - "description": "A short description of what this channel focuses on", - "type": "string" - }, - "id": { - "description": "The actual value that should be sent", - "type": "string" - }, - "refreshRule": { - "description": "In the explore view of a client, this field indicates how this channel should be refreshed. This is an experimental field and subject to change, but for now zero indicates the client should refresh this channel every time a START rating is sent for a type=audio recommendation, while a 1 would indicate it can be refreshed much less often, such as on a 30 minute timer. 2 would indicate even less time to update, say every hour. We are still experimenting on the number of rules necessary and the best implementation for each type of rule. ", - "type": "integer" - } - } - } - ], - "required": [ - "id", - "fullName", - "description" - ], - "type": "object" - }, - "ChannelDocument": { - "allOf": [ - { - "$ref": "#/definitions/CollectionDocument" - }, - { - "properties": { - "attributes": { - "$ref": "#/definitions/ChannelData" - }, - "items": { - "description": "Not used", - "items": { - "type": "object" - }, - "type": "array" - }, - "links": { - "description": "Not used", - "type": "object" - } - }, - "type": "object" - }, - { - "$ref": "#/definitions/AudioItemLinks" - } - ] - }, - "ChannelsData": { - "properties": { - "defaultChannel": { - "default": "npr", - "description": "The default channel NPR recommends", - "type": "string" - } - }, - "type": "object" - }, - "ChannelsDocument": { - "allOf": [ - { - "$ref": "#/definitions/CollectionDocument" - }, - { - "properties": { - "attributes": { - "$ref": "#/definitions/ChannelsData" - }, - "items": { - "description": "The list of individual channels", - "items": { - "$ref": "#/definitions/ChannelDocument" - }, - "type": "array" - }, - "links": { - "description": "Not used", - "type": "object" - } - }, - "type": "object" - } - ] - }, - "CollectionDocument": { - "description": "Base Collection.Doc+JSON output", - "properties": { - "attributes": { - "type": "object" - }, - "errors": { - "description": "A list of encountered errors, ignored on POST, PUT", - "items": { - "type": "object" - }, - "type": "array" - }, - "href": { - "description": "A URL representation of the resource; should generally be ignored by clients unless noted otherwise", - "type": "string" - }, - "items": { - "items": { - "type": "object" - }, - "type": "array" - }, - "links": { - "type": "object" - }, - "version": { - "default": "1.0", - "description": "The version of the Collection.Doc+JSON spec being used", - "type": "string" - } - }, - "required": [ - "version", - "href", - "attributes", - "items", - "links", - "errors" - ], - "type": "object" - }, - "Error": { - "description": "A serialized version of any error encountered when processing this request", - "properties": { - "code": { - "description": "The error code", - "format": "int32", - "type": "integer" - }, - "debug": { - "description": "Additional debug information if debug mode is turned on", - "type": "string" - }, - "text": { - "description": "The error description", - "type": "string" - } - }, - "required": [ - "code" - ], - "type": "object" - }, - "ErrorDocument": { - "allOf": [ - { - "$ref": "#/definitions/CollectionDocument" - }, - { - "properties": { - "attributes": { - "description": "Ignore; will be empty for errors", - "type": "object" - }, - "errors": { - "description": "A list of encountered errors, ignored on POST, PUT", - "items": { - "$ref": "#/definitions/Error" - }, - "type": "array" - }, - "items": { - "description": "Ignore; will be empty for errors", - "items": { - "type": "object" - }, - "type": "array" - }, - "links": { - "description": "Ignore; will be empty for errors", - "type": "object" - } - }, - "type": "object" - } - ], - "description": "A Collection.doc+JSON representation of an error result from an API call" - }, - "Geofence": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "countries": { - "description": "The list of countries as ISO 3166-1 abbreviations in which this media should be available if restricted is true", - "items": { - "type": "string" - }, - "type": "array" - }, - "restricted": { - "default": false, - "description": "Whether any geographic restrictions should be applied", - "type": "boolean" - } - } - } - ], - "description": "The geographic restrictions that should be applied by the client before playing this media", - "required": [ - "restricted", - "countries" - ], - "type": "object" - }, - "ImageLink": { - "allOf": [ - { - "$ref": "#/definitions/AbstractLink" - }, - { - "properties": { - "caption": { - "description": "The caption of the image; can be used as alternate text for accessibility", - "type": "string" - }, - "content-type": { - "default": "image/jpeg", - "description": "The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes.", - "enum": [ - "image/jpeg", - "image/png", - "image/gif" - ], - "type": "string" - }, - "image": { - "description": "A unique identifier for the image", - "type": "string" - }, - "producer": { - "description": "The producer of the image; should be used for properly attributing the image when it exists", - "type": "string" - }, - "provider": { - "description": "The provider of the image; should be used for properly attributing the image when it exists", - "type": "string" - }, - "rel": { - "default": "logo_square", - "description": "The crop type or intended display style/size; note that the enumerated list of possible values is not exhaustive and other values could occur. The list should be treated as examples, rather than absolutes.", - "enum": [ - "logo_square", - "icon", - "wide", - "standard", - "square", - "enlargement", - "custom" - ], - "type": "string" - } - }, - "required": [ - "content-type" - ], - "type": "object" - } - ], - "description": "An image, along with metadata for display" - }, - "OrganizationCategoryAudioListDocument": { - "allOf": [ - { - "$ref": "#/definitions/CollectionDocument" - }, - { - "properties": { - "attributes": { - "$ref": "#/definitions/CategoryData" - }, - "items": { - "description": "An array of Audio Items (recommendations)", - "items": { - "$ref": "#/definitions/AudioItemDocument" - }, - "type": "array" - }, - "links": { - "$ref": "#/definitions/CategoryLinks" - } - }, - "type": "object" - }, - { - "$ref": "#/definitions/AudioItemListDocument" - }, - { - "$ref": "#/definitions/AudioItemLinks" - } - ], - "description": "An array of a certain category of audio recommendations from a provider" - }, - "OrganizationOverviewData": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "brand": { - "$ref": "#/definitions/Brand" - }, - "home": { - "description": "Flag indicating if the current view is in the user's home network", - "type": "boolean" - }, - "type": { - "default": "organization", - "description": "The type of list returned; will always be `organization`", - "enum": [ - "organization" - ], - "type": "string" - } - } - } - ], - "required": [ - "type", - "brand" - ], - "type": "object" - }, - "OrganizationOverviewDocument": { - "allOf": [ - { - "$ref": "#/definitions/CollectionDocument" - }, - { - "properties": { - "attributes": { - "$ref": "#/definitions/OrganizationOverviewData" - }, - "items": { - "description": "A list of separate documents which each include their own list of audio", - "items": { - "$ref": "#/definitions/OrganizationCategoryAudioListDocument" - }, - "type": "array" - }, - "links": { - "$ref": "#/definitions/OrganizationOverviewLinks" - } - }, - "type": "object" - }, - { - "$ref": "#/definitions/AudioItemLinks" - } - ], - "description": "a variety of details about an organization including various lists of recent audio items" - }, - "OrganizationOverviewLinks": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "image": { - "description": "One or more links to an image that can be as for branding (logo and small logo)", - "items": { - "$ref": "#/definitions/ImageLink" - }, - "type": "array" - }, - "related": { - "description": "One or more links to related web pages for the organization (their twitter feed or facebook page for example)", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - }, - "web": { - "description": "One or more links to main page for the organization (their homepage for example)", - "items": { - "$ref": "#/definitions/OtherLink" - }, - "type": "array" - } - } - } - ], - "type": "object" - }, - "OtherLink": { - "allOf": [ - { - "$ref": "#/definitions/AbstractLink" - }, - { - "properties": { - "content-type": { - "default": "application/json", - "description": "The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes.", - "enum": [ - "application/json", - "application/xml", - "text/html" - ], - "type": "string" - }, - "linkText": { - "description": "Text recommended to accompany the link. For example, 'Read Story' with a full story link, or 'Read Transcript' with a transcript link.", - "type": "string" - }, - "pollInterval": { - "description": "When present, the recommended number of seconds between requests to the given URL", - "format": "int32", - "type": "integer" - } - }, - "required": [ - "content-type" - ], - "type": "object" - } - ], - "description": "An individual link from a list of links" - }, - "RatingData": { - "properties": { - "affiliations": { - "description": "An array of IDs \u0026 other data about collections or podcasts the user has ratings for; produced by the server and should be sent back as received; used for tracking program and podcast suggestions", - "items": { - "type": "object" - }, - "type": "array" - }, - "channel": { - "default": "npr", - "description": "The channel this media item was pulled from", - "type": "string" - }, - "cohort": { - "description": "The primary cohort of the current logged-in user", - "type": "string" - }, - "duration": { - "description": "Number of seconds this audio piece is expected to last", - "format": "int32", - "maximum": 9999, - "minimum": 0, - "type": "integer" - }, - "elapsed": { - "description": "Number of seconds since the start of playback for this media item, as an integer", - "format": "int32", - "maximum": 9999, - "minimum": 0, - "type": "integer" - }, - "mediaId": { - "description": "The media id as given by the media object", - "pattern": "^\\d{3,}:[\\w-]{5,}$", - "type": "string" - }, - "origin": { - "description": "How the recommendation was generated", - "pattern": "^[A-Z0-9_]{2,10}$", - "type": "string" - }, - "rating": { - "description": "String representing the rating", - "pattern": "^[A-Z0-9_]{2,10}$", - "type": "string" - }, - "timestamp": { - "description": "ISO-8601 formatted date/time; typically replaced by the client with the actual rating time", - "format": "date-time", - "type": "string" - } - }, - "required": [ - "mediaId", - "origin", - "rating", - "elapsed", - "duration", - "timestamp", - "channel", - "cohort" - ], - "type": "object" - }, - "RecommendationOrganization": { - "allOf": [ - { - "$ref": "#/definitions/AudioItemLinks" - }, - { - "properties": { - "donateUrl": { - "description": "The URL of the organization's donate page", - "type": "string" - }, - "homepageUrl": { - "description": "The URL of the organization's homepage", - "type": "string" - }, - "logoUrl": { - "description": "A URL for an image of the organization's logo", - "type": "string" - }, - "name": { - "description": "The name of the organization", - "type": "string" - } - } - } - ], - "description": "Data about the organization with which this media is associated", - "required": [ - "name" - ], - "type": "object" - }, - "SearchItemDocument": { - "description": "A search result, which is either an AggregationAudioItemListDocument or an AudioItemDocument", - "properties": { - "ifTypeAggregation": { - "$ref": "#/definitions/AggregationAudioItemListDocument" - }, - "ifTypeAudio": { - "$ref": "#/definitions/AudioItemDocument" - }, - "type": { - "description": "The type of search result, which is either an AggregationAudioItemListDocument or an AudioItemDocument", - "enum": [ - "audio", - "aggregation" - ], - "type": "string" - } - }, - "required": [ - "type" - ], - "type": "object" - }, - "SearchListDocument": { - "allOf": [ - { - "$ref": "#/definitions/CollectionDocument" - }, - { - "properties": { - "attributes": { - "$ref": "#/definitions/SearchMetaData" - }, - "items": { - "description": "A list of aggregation or audio items (recommendations)", - "items": { - "$ref": "#/definitions/SearchItemDocument" - }, - "type": "array" - }, - "links": { - "description": "Not used", - "type": "object" - } - }, - "type": "object" - } - ], - "description": "An array of aggregation or audio recommendations" - }, - "SearchMetaData": { - "properties": { - "query": { - "description": "The search terms used in the original request", - "type": "string" - } - }, - "required": [ - "query" - ], - "type": "object" - } - } -} \ No newline at end of file diff --git a/pkg/utils/testdata/oas3-to-oas2/npr/exp-oas2.yaml b/pkg/utils/testdata/oas3-to-oas2/npr/exp-oas2.yaml deleted file mode 100644 index b65025f..0000000 --- a/pkg/utils/testdata/oas3-to-oas2/npr/exp-oas2.yaml +++ /dev/null @@ -1,1345 +0,0 @@ -# Copyright 2024 Google LLC -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http:#www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -swagger: "2.0" -info: - contact: - email: NPROneEnterprise@npr.org - name: NPR One Enterprise Team - url: https://dev.npr.org - description: Audio recommendations tailored to a user's preferences - termsOfService: https://dev.npr.org/guide/prerequisites/terms-of-use - title: NPR Listening Service - version: "2" -host: listening.api.npr.org -schemes: - - https -externalDocs: - description: Learn more at the NPR One Developer Center - url: https://dev.npr.org/guide/services/listening -tags: - - description: Audio recommendations tailored to a user's preferences - name: listening -paths: - /v2/aggregation/{aggId}/recommendations: - get: - description: This endpoint provides a list of recent audio items associated with the aggregation along with metadata about the aggregation. - operationId: getAggRecommendations - parameters: - - $ref: '#/parameters/Authorization' - - description: ID of an aggregation such as a program or podcast. If the specified ID is a program that publishes rundowns, the latest rundown will be returned. - format: int64 - in: path - name: aggId - required: true - type: integer - - default: 0 - description: The result to start with. Allows paging through the episodes of a podcast or program, with the default, `startNum=0`, being the most recent episode. Ignored for programs that publish a rundown. - format: int32 - in: query - name: startNum - type: integer - responses: - "200": - description: A list of audio items from the specified aggregation - headers: - X-RateLimit-Limit: - description: The number of allowed requests in the current period - type: integer - X-RateLimit-Remaining: - description: The number of remaining requests in the current period - type: integer - X-RateLimit-Reset: - description: The number of seconds left in the current period - type: integer - "401": - $ref: '#/responses/401WithDocument' - "404": - $ref: '#/responses/404WithDocument' - "429": - $ref: '#/responses/429WithDocument' - "500": - $ref: '#/responses/500WithDocument' - "503": - $ref: '#/responses/503WithDocument' - security: - - oauth2: - - listening.readonly - summary: Get a set of recommendations for an aggregation independent of the user's listening history - tags: - - listening - /v2/channels: - get: - description: These channels allow the user to specify a focus for the content returned in the recommendations endpoint. - operationId: getChannels - parameters: - - $ref: '#/parameters/Authorization' - - default: false - description: If set to `true`, this call will return only channels that should be shown in the client's `Explore` view - in: query - name: exploreOnly - type: boolean - responses: - "200": - description: A list of channels - headers: - X-RateLimit-Limit: - description: The number of allowed requests in the current period - type: integer - X-RateLimit-Remaining: - description: The number of remaining requests in the current period - type: integer - X-RateLimit-Reset: - description: The number of seconds left in the current period - type: integer - "401": - $ref: '#/responses/401WithDocument' - "429": - $ref: '#/responses/429WithDocument' - "503": - $ref: '#/responses/503WithDocument' - security: - - oauth2: - - listening.readonly - summary: Get the list of available channels - tags: - - listening - /v2/history: - get: - description: This endpoint provides the list of recently-rated audio recommendations that the logged-in user has consumed. Some rated recommendations are filtered, such as sponsorship and donation. - operationId: getHistory - parameters: - - $ref: '#/parameters/Authorization' - responses: - "200": - $ref: '#/responses/ListeningSuccess' - "401": - $ref: '#/responses/401WithDocument' - "429": - $ref: '#/responses/429WithDocument' - "500": - $ref: '#/responses/500WithDocument' - "503": - $ref: '#/responses/503WithDocument' - security: - - oauth2: - - listening.readonly - summary: Get recent ratings the logged-in user has submitted - tags: - - listening - /v2/organizations/{orgId}/categories/{category}/recommendations: - get: - description: This endpoint provides a list of recommendations from a category of content from an organization. - operationId: getOrganizationCategory - parameters: - - $ref: '#/parameters/Authorization' - - default: story - description: One of the three categories of content - newscast, story, or podcast - enum: - - newscast - - story - - podcast - in: path - name: category - required: true - type: string - - description: ID of an organization, such as an NPR One station - format: int64 - in: path - name: orgId - required: true - type: integer - responses: - "200": - description: A list of audio items from a category of content from an organization - headers: - X-RateLimit-Limit: - description: The number of allowed requests in the current period - type: integer - X-RateLimit-Remaining: - description: The number of remaining requests in the current period - type: integer - X-RateLimit-Reset: - description: The number of seconds left in the current period - type: integer - "401": - $ref: '#/responses/401WithDocument' - "404": - $ref: '#/responses/404WithDocument' - "429": - $ref: '#/responses/429WithDocument' - "500": - $ref: '#/responses/500WithDocument' - "503": - $ref: '#/responses/503WithDocument' - security: - - oauth2: - - listening.readonly - summary: Get a list of recommendations from a category of content from an organization - tags: - - listening - /v2/organizations/{orgId}/recommendations: - get: - description: This endpoint provides a variety of details about an organization including various lists of recent audio items. - operationId: getOrganizationOverview - parameters: - - $ref: '#/parameters/Authorization' - - description: ID of an organization, such as an NPR One station - format: int64 - in: path - name: orgId - required: true - type: integer - responses: - "200": - description: A list of up to four different categories of audio items from a specific organization - headers: - X-RateLimit-Limit: - description: The number of allowed requests in the current period - type: integer - X-RateLimit-Remaining: - description: The number of remaining requests in the current period - type: integer - X-RateLimit-Reset: - description: The number of seconds left in the current period - type: integer - "401": - $ref: '#/responses/401WithDocument' - "404": - $ref: '#/responses/404WithDocument' - "429": - $ref: '#/responses/429WithDocument' - "500": - $ref: '#/responses/500WithDocument' - "503": - $ref: '#/responses/503WithDocument' - security: - - oauth2: - - listening.readonly - summary: Get a variety of details about an organization including various lists of recent audio items - tags: - - listening - /v2/promo/recommendations: - get: - description: Gets the most recently played promo for which the user has neither tapped through the promo or listened to the target story. - operationId: getPromo - parameters: - - $ref: '#/parameters/Authorization' - responses: - "200": - $ref: '#/responses/ListeningSuccess' - "401": - $ref: '#/responses/401WithDocument' - "429": - $ref: '#/responses/429WithDocument' - "500": - $ref: '#/responses/500WithDocument' - "503": - $ref: '#/responses/503WithDocument' - security: - - oauth2: - - listening.readonly - summary: Retrieve the most recent promo audio heard by the logged-in user - tags: - - listening - /v2/ratings: - post: - description: |- - This endpoint is the main mechanism for providing feedback from the user to NPR about the recommendations that are obtained from `GET /listening/v2/recommendations`. - - A fully-populated link to this endpoint is returned with each individual recommendation and is located in the AudioItemDocument under the `links['recommendations']` object. The query parameters in this link should not be modified. - Be sure to copy and send back the entire ratings object (RatingData), as new fields may be added to it in the future. - - This endpoint can return a blank JSON.doc or AudioItemDocument depending on the `recommend=true|false` parameter. The `recommend=true` flag allows this endpoint to both receive ratings and send back recommendations in the same call. - operationId: postRating - parameters: - - $ref: '#/parameters/Authorization' - - $ref: '#/parameters/X-Advertising-ID' - - $ref: '#/parameters/channel' - - default: true - description: If set to `false`, this call will return a blank document; otherwise it will return a new recommendation object - in: query - name: recommend - type: boolean - responses: - "200": - description: If the `recommend` param was set to `true`, this returns a list of audio items; otherwise, a blank document is returned. - headers: - X-RateLimit-Limit: - description: The number of allowed requests in the current period - type: integer - X-RateLimit-Remaining: - description: The number of remaining requests in the current period - type: integer - X-RateLimit-Reset: - description: The number of seconds left in the current period - type: integer - "400": - $ref: '#/responses/400WithDocument' - "401": - $ref: '#/responses/401WithDocument' - "429": - $ref: '#/responses/429WithDocument' - "500": - $ref: '#/responses/500WithDocument' - "503": - $ref: '#/responses/503WithDocument' - security: - - oauth2: - - listening.write - summary: Collect new ratings for media previously recommended to the logged-in user - tags: - - listening - /v2/recommendations: - get: - description: |- - This endpoint returns a list of audio recommendations. It is designed to be used for an initial list of recommendations, and then `POST /v2/ratings?recommend=true` should be used for subsequent requests for recommendations. - - A fully-populated link to the ratings endpoint is returned with each individual recommendation and is located in the AudioItemDocument under the `links['recommendations']` object. The query parameters in this link should not be modified. - Be sure to copy and send back the entire ratings object (RatingData), as new fields may be added to it in the future. - - A 500 will be returned if there are no eligible remaining recommendations. - operationId: getRecommendations - parameters: - - $ref: '#/parameters/Authorization' - - $ref: '#/parameters/X-Advertising-ID' - - $ref: '#/parameters/channel' - - description: The user received a push notification about this media; if provided, the service will add this recommendation to the top of the list - in: query - name: notifiedMediaId - type: string - - description: This media was shared directly with the user; if provided, the service will add this recommendation to the top of the list - in: query - name: sharedMediaId - type: string - responses: - "200": - $ref: '#/responses/ListeningSuccess' - "400": - $ref: '#/responses/400WithDocument' - "401": - $ref: '#/responses/401WithDocument' - "429": - $ref: '#/responses/429WithDocument' - "500": - $ref: '#/responses/500WithDocument' - "503": - $ref: '#/responses/503WithDocument' - security: - - oauth2: - - listening.readonly - summary: Get a list of media for the logged-in user from NPR's recommendation engine - tags: - - listening - /v2/search/recommendations: - get: - description: In the schema shown below, SearchItemDocument is not an actual type of returned object; the object returned by a search will be either an AggregationAudioItemListDocument or an AudioItemDocument. - operationId: getSearchRecommendations - parameters: - - $ref: '#/parameters/Authorization' - - description: Search terms to search on; can include URL-encoded punctuation - in: query - name: searchTerms - required: true - type: string - responses: - "200": - description: A list of audio and aggregation items matching the search query - headers: - X-RateLimit-Limit: - description: The number of allowed requests in the current period - type: integer - X-RateLimit-Remaining: - description: The number of remaining requests in the current period - type: integer - X-RateLimit-Reset: - description: The number of seconds left in the current period - type: integer - "401": - $ref: '#/responses/401WithDocument' - "429": - $ref: '#/responses/429WithDocument' - "500": - $ref: '#/responses/500WithDocument' - "503": - $ref: '#/responses/503WithDocument' - security: - - oauth2: - - listening.readonly - summary: Get a list of recent audio and aggregation items associated with search terms - tags: - - listening -securityDefinitions: - oauth2: - authorizationUrl: https://authorization.api.npr.org/v2/authorize - flow: implicit - scopes: - identity.readonly: See your personal information, such as your first name, last name, and favorite station. - identity.write: Update your personal information, such as your favorite station(s) or program(s) you follow, on your behalf. - listening.readonly: See your NPR One listening history and get audio recommendations. - listening.write: Record that you have heard, marked as interesting, and/or skipped NPR One stories in order to personalize future audio recommendations. - localactivation: Connect you with your local NPR member station for communication purposes. - type: oauth2 -parameters: - Authorization: - description: Your access token from the Authorization Service. Should start with `Bearer`, followed by a space, followed by the token. - in: header - name: Authorization - required: true - type: string - X-Advertising-ID: - description: A device-specific advertising identifier, if possible. Apple's IDFA is an example. - in: header - name: X-Advertising-ID - type: string - channel: - default: npr - description: Determines the focus of the recommendations returned. Channel `npr` is recommended for most use cases. - enum: - - npr - - followed - - recommended - - emailstories - - emailprograms - - lapsedusersemail - - ongoing email - - newscasts - - shows - in: query - name: channel - type: string -responses: - 400WithDocument: - description: A bad request; generally, one or more parameters passed in were incorrect or missing - headers: - X-RateLimit-Limit: - description: The number of allowed requests in the current period - type: integer - X-RateLimit-Remaining: - description: The number of remaining requests in the current period - type: integer - X-RateLimit-Reset: - description: The number of seconds left in the current period - type: integer - 401WithDocument: - description: The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers. - 404WithDocument: - description: The resource with the requested ID could not be found, and the server was unable to complete the request. - headers: - X-RateLimit-Limit: - description: The number of allowed requests in the current period - type: integer - X-RateLimit-Remaining: - description: The number of remaining requests in the current period - type: integer - X-RateLimit-Reset: - description: The number of seconds left in the current period - type: integer - 429WithDocument: - description: The client has exceeded the number of daily calls as per their rate limit. For now, this only applies to prototype applications and untrusted clients. Trusted clients will never be rate-limited, nor will any production apps. - headers: - X-RateLimit-Limit: - description: The number of allowed requests in the current period - type: integer - X-RateLimit-Remaining: - description: The number of remaining requests in the current period - type: integer - X-RateLimit-Reset: - description: The number of seconds left in the current period - type: integer - 500WithDocument: - description: A server error - headers: - X-RateLimit-Limit: - description: The number of allowed requests in the current period - type: integer - X-RateLimit-Remaining: - description: The number of remaining requests in the current period - type: integer - X-RateLimit-Reset: - description: The number of seconds left in the current period - type: integer - 503WithDocument: - description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up. - headers: - Retry-After: - description: The predicted time the system will be back up - format: date-time - type: string - ListeningSuccess: - description: A list of audio items (recommendations) - headers: - X-RateLimit-Limit: - description: The number of allowed requests in the current period - type: integer - X-RateLimit-Remaining: - description: The number of remaining requests in the current period - type: integer - X-RateLimit-Reset: - description: The number of seconds left in the current period - type: integer -definitions: - AbstractCDocLink: - allOf: - - $ref: '#/definitions/AbstractLink' - - properties: - content-type: - description: The MIME type of the response of this link - type: string - required: - - content-type - type: object - AbstractLink: - properties: - href: - description: The link to be followed - format: uri - type: string - required: - - href - type: object - Affiliation: - description: A program (aggregation) that a given user has shown an affiliation with - properties: - daysSinceLastListen: - description: The number of days since a user last listened to a story from this aggregation. Absent if user never listened to the aggregation. - format: int32 - type: integer - following: - default: false - description: Whether or not the user is following the aggregation. When changing affiliation status, the client is expected to toggle this value and then send the entire object back. - type: boolean - href: - description: A link to more details about the program from the NPR Story API - type: string - id: - description: A unique identifier for the aggregation (program) - format: int64 - type: integer - notif_following: - description: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they follow. - items: - type: string - type: array - notif_rated: - description: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they have highly rated. - items: - type: string - type: array - rating: - description: The user's average rating for this affiliation on a scale of 0-1. Absent if user never listened to the aggregation. - format: float - type: number - title: - description: The title for the aggregation (program) - type: string - required: - - id - - href - - following - type: object - AggregationAudioItemListDocument: - allOf: - - $ref: '#/definitions/CollectionDocument' - - properties: - attributes: - $ref: '#/definitions/AggregationData' - items: - description: An array of Audio Items (recommendations) - items: - $ref: '#/definitions/AudioItemDocument' - type: array - links: - $ref: '#/definitions/AggregationLinks' - type: object - - $ref: '#/definitions/AudioItemListDocument' - - $ref: '#/definitions/AudioItemLinks' - description: An array of audio recommendations with additional metadata about the aggregation they are associated with - AggregationData: - allOf: - - $ref: '#/definitions/AudioItemListDocument' - - $ref: '#/definitions/AudioItemLinks' - - properties: - affiliation: - description: A unique identifier for the aggregation - type: string - affiliationMeta: - $ref: '#/definitions/Affiliation' - description: - description: A short description or teaser - type: string - provider: - default: NPR - description: The producer of this aggregation - type: string - station: - default: NPR - description: Deprecated - clients should switch to use provider. - type: string - title: - description: The title of this aggregation - type: string - type: - default: aggregation - description: The type of list returned; will always be `aggregation`; useful for parsing search results - enum: - - aggregation - type: string - required: - - type - - affiliation - - title - type: object - AggregationLinks: - allOf: - - $ref: '#/definitions/AudioItemListDocument' - - $ref: '#/definitions/AudioItemLinks' - - properties: - binge: - description: One or more links to more unrated / unheard recommendations from this aggregation - items: - $ref: '#/definitions/OtherLink' - type: array - image: - description: One or more links to an image, along with metadata for display - items: - $ref: '#/definitions/ImageLink' - type: array - more: - description: One or more links to more episodes for the aggregation - items: - $ref: '#/definitions/OtherLink' - type: array - web: - description: One or more links to a web page for the item - items: - $ref: '#/definitions/OtherLink' - type: array - type: object - AudioItemData: - allOf: - - $ref: '#/definitions/AudioItemLinks' - - properties: - album: - description: Album information associated with the media - type: string - artist: - description: The artist associated with the media - type: string - audioTitle: - description: For first-party client use only - type: string - bingeAggId: - description: Indicates which aggregration ID this recommendation was binged from - type: string - button: - description: The text contents of an action button displayed on the client - type: string - date: - description: The publication date in ISO-8601 format - format: date-time - type: string - description: - description: A short description or teaser - type: string - duration: - description: The length of the audio content in seconds - format: int32 - maximum: 9999 - minimum: 0 - type: integer - expires: - description: The media's expiration date in ISO-8601 format - format: date-time - type: string - geofence: - $ref: '#/definitions/Geofence' - inFlow: - description: Indicates the likelihood of being within a flow, useful for stateful playback buttons - type: boolean - label: - description: The record label associated with the media - type: string - organization: - $ref: '#/definitions/RecommendationOrganization' - primary: - description: Whether the audio is the primary audio of the story to which it is associated - type: boolean - program: - description: The program associated with this media - type: string - provider: - default: NPR - description: The name of the organization providing this media - type: string - rating: - $ref: '#/definitions/RatingData' - rationale: - description: A short summary of why this content was recommended - type: string - skippable: - default: true - description: Whether the client should allow this content to be skipped - type: boolean - slug: - description: A tag or category for this media - type: string - song: - description: The song title associated with the media - type: string - streamGuid: - description: The full GUID of the live stream returned within the recommendation - type: string - title: - description: The title of this media - type: string - type: - default: audio - description: Help determine how content is displayed; for more information, see our design guidelines - enum: - - audio - - sponsorship - - stationId - - intro - - donate - - featureCardInformational - - featureCardNotification - - featureCardPromotion - - featureCardExternalLink - - featureCardAsyncRequest - type: string - uid: - description: The media ID (for use in ratings objects) - pattern: ^\d{3,}:[\w-]{5,}$ - type: string - unavailableText: - description: The text contents to be displayed on the client if no media URLs are available - type: string - required: - - type - - uid - - title - - skippable - - rationale - - rating - type: object - AudioItemDocument: - allOf: - - $ref: '#/definitions/CollectionDocument' - - properties: - attributes: - $ref: '#/definitions/AudioItemData' - items: - description: Not used - items: - type: object - type: array - links: - $ref: '#/definitions/AudioItemLinks' - type: object - - $ref: '#/definitions/AudioItemLinks' - AudioItemLinks: - properties: - action: - description: One or more links to be trigged by user actions, usually when a button is clicked - items: - $ref: '#/definitions/OtherLink' - type: array - audio: - description: One or more links to audio files for the item - items: - $ref: '#/definitions/AudioLink' - type: array - binge: - description: One or more links that start a flow-based experience focused on the aggregation - items: - $ref: '#/definitions/OtherLink' - type: array - image: - description: One or more links to an image, along with metadata for display - items: - $ref: '#/definitions/ImageLink' - type: array - onramps: - description: One or more shareable links for the item - items: - $ref: '#/definitions/OtherLink' - type: array - ratings: - description: This is an alternate URL to use to POST the ratings JSON. Difference between this and 'recommendations' is that 'ratings' will NOT return back recommendations of audio to play next. - items: - $ref: '#/definitions/OtherLink' - type: array - recommendations: - description: This is the URL that should be POSTed with the ratings JSON when this audio starts to play - items: - $ref: '#/definitions/OtherLink' - type: array - stream-metadata: - description: Links that can be polled to retreive current program metadata for a given stream - items: - $ref: '#/definitions/OtherLink' - type: array - up: - description: One or more links to more details about the program or podcast with which this item is associated - items: - $ref: '#/definitions/OtherLink' - type: array - web: - description: One or more links to a web page for the item - items: - $ref: '#/definitions/OtherLink' - type: array - type: object - AudioItemListDocument: - allOf: - - $ref: '#/definitions/CollectionDocument' - - properties: - attributes: - description: Not used - type: object - items: - description: An array of Audio Items (recommendations) - items: - $ref: '#/definitions/AudioItemDocument' - type: array - links: - description: Not used - type: object - type: object - AudioLink: - allOf: - - $ref: '#/definitions/AbstractLink' - - properties: - content-type: - default: audio/aac - description: The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes. - enum: - - audio/mp3 - - audio/aac - - audio/3gp - - application/vnd.apple.mpegurl - - audio/x-ms-wax - type: string - required: - - content-type - type: object - description: A link to audio files for the item - AudioPlaylistData: - allOf: - - $ref: '#/definitions/AudioItemListDocument' - - $ref: '#/definitions/AudioItemLinks' - - properties: - id: - description: The globally unique identifier for the playlist. - type: string - title: - description: The user-editable title of the playlist - type: string - uids: - description: Individual content identifiers; see AudioItemDocument - items: - type: string - type: array - required: - - id - - title - - uids - type: object - AudioPlaylistDocument: - allOf: - - $ref: '#/definitions/AudioItemListDocument' - - properties: - attributes: - $ref: '#/definitions/AudioPlaylistData' - items: - description: An array of Audio Items (recommendations) - items: - $ref: '#/definitions/AudioItemDocument' - type: array - links: - $ref: '#/definitions/OtherLink' - type: object - - $ref: '#/definitions/AudioItemListDocument' - - $ref: '#/definitions/AudioItemLinks' - Brand: - allOf: - - $ref: '#/definitions/AudioItemLinks' - - properties: - band: - description: The radio band for the organization if they are a station (AM or FM) - type: string - call: - description: The call letter for the organization if they are a station - type: string - frequency: - description: The radio frequency for the organization if they are a station - type: string - marketCity: - description: The market city for the organization - type: string - marketState: - description: The market state for the organization - type: string - name: - description: The name of the organization - type: string - tagline: - description: The tagline for the organization - type: string - description: Branding information for the organization - required: - - name - - call - - marketCity - type: object - CategoryData: - allOf: - - $ref: '#/definitions/AudioItemListDocument' - - $ref: '#/definitions/AudioItemLinks' - - properties: - displayType: - description: How clients should display this channel in the station profile view - enum: - - default - - show - - playable - - newscast - type: string - title: - description: The title of this category - type: string - type: - default: category - description: The type of list returned; will always be `category` - type: string - required: - - type - - title - type: object - CategoryLinks: - allOf: - - $ref: '#/definitions/AudioItemListDocument' - - $ref: '#/definitions/AudioItemLinks' - - properties: - more: - description: One or more links to more episodes for the aggregation - items: - $ref: '#/definitions/OtherLink' - type: array - type: object - ChannelData: - allOf: - - $ref: '#/definitions/AudioItemLinks' - - properties: - description: - description: A longer description of what this channel focuses on - type: string - displayType: - description: How clients should display this channel in the explore view - enum: - - default - - show - - playable - - newscast - type: string - emptyText: - description: Text for clients to display when the channel contains no recommendations - type: string - fullName: - description: A short description of what this channel focuses on - type: string - id: - description: The actual value that should be sent - type: string - refreshRule: - description: 'In the explore view of a client, this field indicates how this channel should be refreshed. This is an experimental field and subject to change, but for now zero indicates the client should refresh this channel every time a START rating is sent for a type=audio recommendation, while a 1 would indicate it can be refreshed much less often, such as on a 30 minute timer. 2 would indicate even less time to update, say every hour. We are still experimenting on the number of rules necessary and the best implementation for each type of rule. ' - type: integer - required: - - id - - fullName - - description - type: object - ChannelDocument: - allOf: - - $ref: '#/definitions/CollectionDocument' - - properties: - attributes: - $ref: '#/definitions/ChannelData' - items: - description: Not used - items: - type: object - type: array - links: - description: Not used - type: object - type: object - - $ref: '#/definitions/AudioItemLinks' - ChannelsData: - properties: - defaultChannel: - default: npr - description: The default channel NPR recommends - type: string - type: object - ChannelsDocument: - allOf: - - $ref: '#/definitions/CollectionDocument' - - properties: - attributes: - $ref: '#/definitions/ChannelsData' - items: - description: The list of individual channels - items: - $ref: '#/definitions/ChannelDocument' - type: array - links: - description: Not used - type: object - type: object - CollectionDocument: - description: Base Collection.Doc+JSON output - properties: - attributes: - type: object - errors: - description: A list of encountered errors, ignored on POST, PUT - items: - type: object - type: array - href: - description: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - type: string - items: - items: - type: object - type: array - links: - type: object - version: - default: "1.0" - description: The version of the Collection.Doc+JSON spec being used - type: string - required: - - version - - href - - attributes - - items - - links - - errors - type: object - Error: - description: A serialized version of any error encountered when processing this request - properties: - code: - description: The error code - format: int32 - type: integer - debug: - description: Additional debug information if debug mode is turned on - type: string - text: - description: The error description - type: string - required: - - code - type: object - ErrorDocument: - allOf: - - $ref: '#/definitions/CollectionDocument' - - properties: - attributes: - description: Ignore; will be empty for errors - type: object - errors: - description: A list of encountered errors, ignored on POST, PUT - items: - $ref: '#/definitions/Error' - type: array - items: - description: Ignore; will be empty for errors - items: - type: object - type: array - links: - description: Ignore; will be empty for errors - type: object - type: object - description: A Collection.doc+JSON representation of an error result from an API call - Geofence: - allOf: - - $ref: '#/definitions/AudioItemLinks' - - properties: - countries: - description: The list of countries as ISO 3166-1 abbreviations in which this media should be available if restricted is true - items: - type: string - type: array - restricted: - default: false - description: Whether any geographic restrictions should be applied - type: boolean - description: The geographic restrictions that should be applied by the client before playing this media - required: - - restricted - - countries - type: object - ImageLink: - allOf: - - $ref: '#/definitions/AbstractLink' - - properties: - caption: - description: The caption of the image; can be used as alternate text for accessibility - type: string - content-type: - default: image/jpeg - description: The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes. - enum: - - image/jpeg - - image/png - - image/gif - type: string - image: - description: A unique identifier for the image - type: string - producer: - description: The producer of the image; should be used for properly attributing the image when it exists - type: string - provider: - description: The provider of the image; should be used for properly attributing the image when it exists - type: string - rel: - default: logo_square - description: The crop type or intended display style/size; note that the enumerated list of possible values is not exhaustive and other values could occur. The list should be treated as examples, rather than absolutes. - enum: - - logo_square - - icon - - wide - - standard - - square - - enlargement - - custom - type: string - required: - - content-type - type: object - description: An image, along with metadata for display - OrganizationCategoryAudioListDocument: - allOf: - - $ref: '#/definitions/CollectionDocument' - - properties: - attributes: - $ref: '#/definitions/CategoryData' - items: - description: An array of Audio Items (recommendations) - items: - $ref: '#/definitions/AudioItemDocument' - type: array - links: - $ref: '#/definitions/CategoryLinks' - type: object - - $ref: '#/definitions/AudioItemListDocument' - - $ref: '#/definitions/AudioItemLinks' - description: An array of a certain category of audio recommendations from a provider - OrganizationOverviewData: - allOf: - - $ref: '#/definitions/AudioItemLinks' - - properties: - brand: - $ref: '#/definitions/Brand' - home: - description: Flag indicating if the current view is in the user's home network - type: boolean - type: - default: organization - description: The type of list returned; will always be `organization` - enum: - - organization - type: string - required: - - type - - brand - type: object - OrganizationOverviewDocument: - allOf: - - $ref: '#/definitions/CollectionDocument' - - properties: - attributes: - $ref: '#/definitions/OrganizationOverviewData' - items: - description: A list of separate documents which each include their own list of audio - items: - $ref: '#/definitions/OrganizationCategoryAudioListDocument' - type: array - links: - $ref: '#/definitions/OrganizationOverviewLinks' - type: object - - $ref: '#/definitions/AudioItemLinks' - description: a variety of details about an organization including various lists of recent audio items - OrganizationOverviewLinks: - allOf: - - $ref: '#/definitions/AudioItemLinks' - - properties: - image: - description: One or more links to an image that can be as for branding (logo and small logo) - items: - $ref: '#/definitions/ImageLink' - type: array - related: - description: One or more links to related web pages for the organization (their twitter feed or facebook page for example) - items: - $ref: '#/definitions/OtherLink' - type: array - web: - description: One or more links to main page for the organization (their homepage for example) - items: - $ref: '#/definitions/OtherLink' - type: array - type: object - OtherLink: - allOf: - - $ref: '#/definitions/AbstractLink' - - properties: - content-type: - default: application/json - description: The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes. - enum: - - application/json - - application/xml - - text/html - type: string - linkText: - description: Text recommended to accompany the link. For example, 'Read Story' with a full story link, or 'Read Transcript' with a transcript link. - type: string - pollInterval: - description: When present, the recommended number of seconds between requests to the given URL - format: int32 - type: integer - required: - - content-type - type: object - description: An individual link from a list of links - RatingData: - properties: - affiliations: - description: An array of IDs & other data about collections or podcasts the user has ratings for; produced by the server and should be sent back as received; used for tracking program and podcast suggestions - items: - type: object - type: array - channel: - default: npr - description: The channel this media item was pulled from - type: string - cohort: - description: The primary cohort of the current logged-in user - type: string - duration: - description: Number of seconds this audio piece is expected to last - format: int32 - maximum: 9999 - minimum: 0 - type: integer - elapsed: - description: Number of seconds since the start of playback for this media item, as an integer - format: int32 - maximum: 9999 - minimum: 0 - type: integer - mediaId: - description: The media id as given by the media object - pattern: ^\d{3,}:[\w-]{5,}$ - type: string - origin: - description: How the recommendation was generated - pattern: ^[A-Z0-9_]{2,10}$ - type: string - rating: - description: String representing the rating - pattern: ^[A-Z0-9_]{2,10}$ - type: string - timestamp: - description: ISO-8601 formatted date/time; typically replaced by the client with the actual rating time - format: date-time - type: string - required: - - mediaId - - origin - - rating - - elapsed - - duration - - timestamp - - channel - - cohort - type: object - RecommendationOrganization: - allOf: - - $ref: '#/definitions/AudioItemLinks' - - properties: - donateUrl: - description: The URL of the organization's donate page - type: string - homepageUrl: - description: The URL of the organization's homepage - type: string - logoUrl: - description: A URL for an image of the organization's logo - type: string - name: - description: The name of the organization - type: string - description: Data about the organization with which this media is associated - required: - - name - type: object - SearchItemDocument: - description: A search result, which is either an AggregationAudioItemListDocument or an AudioItemDocument - properties: - ifTypeAggregation: - $ref: '#/definitions/AggregationAudioItemListDocument' - ifTypeAudio: - $ref: '#/definitions/AudioItemDocument' - type: - description: The type of search result, which is either an AggregationAudioItemListDocument or an AudioItemDocument - enum: - - audio - - aggregation - type: string - required: - - type - type: object - SearchListDocument: - allOf: - - $ref: '#/definitions/CollectionDocument' - - properties: - attributes: - $ref: '#/definitions/SearchMetaData' - items: - description: A list of aggregation or audio items (recommendations) - items: - $ref: '#/definitions/SearchItemDocument' - type: array - links: - description: Not used - type: object - type: object - description: An array of aggregation or audio recommendations - SearchMetaData: - properties: - query: - description: The search terms used in the original request - type: string - required: - - query - type: object