swagger-api / swagger-api/swagger-parser
java.lang.NullPointerException at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:852)
Open
@ralphdoe is already working on this.
Since Jun 7, 2018.
- Dominant language
- Java
- Stars
- 867
- Forks
- 560
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 7
Description
java.lang.NullPointerException
at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:852)
at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:830)
at io.swagger.v3.parser.converter.SwaggerConverter.lambda$convert$11(SwaggerConverter.java:1083)
at java.util.LinkedHashMap.forEach(LinkedHashMap.java:684)
at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:1082)
at java.util.stream.ReferencePipeline$3$1.accept(ReferencePipeline.java:193)
at java.util.ArrayList$ArrayListSpliterator.forEachRemaining(ArrayList.java:1382)
at java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:481)
at java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:471)
at java.util.stream.ReduceOps$ReduceOp.evaluateSequential(ReduceOps.java:708)
at java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234)
at java.util.stream.ReferencePipeline.collect(ReferencePipeline.java:499)
at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:1064)
at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:215)
at io.swagger.v3.parser.converter.SwaggerConverter.readLocation(SwaggerConverter.java:93)
at io.swagger.v3.parser.OpenAPIV3Parser.read(OpenAPIV3Parser.java:90)
at io.swagger.v3.parser.OpenAPIV3Parser.read(OpenAPIV3Parser.java:78)
while parsing:
swagger: '2.0'
schemes:
- https
host: api.npr.org
info:
contact:
email: NPROneEnterprise@npr.org
name: NPR One Enterprise Team
url: 'http://dev.npr.org'
description: |-
NPR One is a smart application that brings the best of NPR and Member Station programming, newscasts,
podcasts, and stories together to create a new experience for listening. It provides an editor-curated and
localized mobile listening experience based on the content the listener chooses, likes, shares, and enjoys.
The API provides all of the content and customization in a simple, structured way that is easy for application
developers to implement.
termsOfService: 'http://dev.npr.org/develop/terms-of-use'
title: NPR One API Reference
version: Calcium
x-apisguru-categories:
- media
x-logo:
url: 'https://pbs.twimg.com/profile_images/722199003845304320/s2zwEoao_400x400.jpg'
x-origin:
- format: swagger
url: 'https://api.npr.org/documentation/calcium/swagger.json'
version: '2.0'
x-providerName: npr.org
externalDocs:
description: Learn more at the NPR One Developer Center
url: 'http://dev.npr.org'
consumes:
- application/json
- application/vnd.collection.doc+json
produces:
- application/json
- application/vnd.collection.doc+json
- 'application/hal+json '
securityDefinitions:
oauth2:
authorizationUrl: 'https://api.npr.org/authorization/v2/authorize'
flow: accessCode
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.
tokenUrl: 'https://api.npr.org/authorization/v2/token'
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
required: false
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
required: false
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
schema:
$ref: '#/definitions/ErrorDocument'
401WithDocument:
description: The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers.
schema:
$ref: '#/definitions/ErrorDocument'
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
schema:
$ref: '#/definitions/ErrorDocument'
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
schema:
$ref: '#/definitions/ErrorDocument'
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
schema:
$ref: '#/definitions/ErrorDocument'
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
schema:
$ref: '#/definitions/ErrorDocument'
IdentitySuccess:
description: The request was successful
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
schema:
$ref: '#/definitions/UserDocument'
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
schema:
$ref: '#/definitions/AudioItemListDocument'
Simple400:
description: 'A bad request; generally, one or more parameters passed in were incorrect or missing'
schema:
$ref: '#/definitions/SimpleError'
Simple401:
description: The client credentials were invalid or the authorization server denied the request.
schema:
$ref: '#/definitions/SimpleError'
Simple500:
description: A server error
schema:
$ref: '#/definitions/SimpleError'
Simple503:
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
schema:
$ref: '#/definitions/SimpleError'
tags:
- description: The interface to our OAuth2 server
name: authorization
- description: The entry point to user-specific information
name: identity
- description: Audio recommendations tailored to a user's preferences
name: listening
- description: Connects users to their local stations
name: localactivation
- description: Sponsorship for non-NPR One client applications
name: sponsorship
- description: 'Allows clients to look up information for organizations that partner with NPR, including stations and third-party content providers.'
name: organizationDataService
- description: Allows clients to look up NPR member station information
name: stationfinder
paths:
/authorization/v2/authorize:
get:
description: |-
If the parameters passed to this endpoint are correct, it will redirect to `npr.org/oauth2/login` for the user to complete the sign-in.
Currently acceptable values for `scope` are any combination of the following:
- `identity.readonly` - for read-only access to the Identity Service
- `identity.write` - for write access to the Identity Service
- `listening.readonly` - for read-only access to the Listening Service
- `listening.write` - for write access to the Listening Service
- `localactivation` - for all access to the Local Activation Service
It is generally suggested that you assume that you will need all of the current scopes in order to successfully implement an NPR One application.
If the parameters passed in are NOT correct and the client passed in a valid `redirect_uri` parameter, the request will be redirected to `{{YOUR_REDIRECT_URI}}?error={{ERROR_TYPE}}&message={{ERROR_DESCRIPTION}}`.
If the parameters passed are NOT correct and the client did not pass in a valid `redirect_uri` parameter, this endpoint will return the errors encoded as JSON objects (along with the corresponding HTTP status code -- usually 400).
The latter is intended for development and debugging purposes -- in a real-world situation, errors returned as JSON objects are irretrievable by the client application, and thus passing in a valid `redirect_uri` is critical even for the purpose of capturing errors.
If the user successfully logs in and authorizes the application, the request will be redirected to `{{YOUR_REDIRECT_URI}}?code={{AUTHORIZATION_CODE}}&state={{CSRF_TOKEN}}`
If the user DENIES the application, they will be redirected to `{{YOUR_REDIRECT_URI}}?error=denied&message=The%20user%20has%20denied%20the%20login%20and%20access%20request&state={{CSRF_TOKEN}}`.
This means that if your application flow requires a user to log in in order to proceed, it is up to you to give them the proper messaging explaining that the sign-in must be authorized in order to continue.
Finally, please do not confuse an authorization code with an access token. Once your app has completed this flow, you will still need to call `POST /authorization/v2/token` in order to swap the code for a valid access token.
operationId: getAuthorizationPage
parameters:
- description: The client's ID
in: query
name: client_id
required: true
type: string
- description: The client's URL to redirect to if the authentication is approved
in: query
name: redirect_uri
required: true
type: string
- description: 'The type of response; currently, only `code` is supported'
enum:
- code
in: query
name: response_type
required: true
type: string
- description: A space-separated list of scope(s) requested by the application
in: query
name: scope
required: true
type: string
- description: 'A CSRF token generated by the client, to be roundtripped through the request for added security'
in: query
name: state
required: true
type: string
produces:
- text/html
responses:
'302':
description: 'The correct parameters were passed in and we are redirecting to the authentication page; OR, a valid `redirect_uri` was supplied but there was another error, and the error type and message are embedded in the querystring.'
headers:
Location:
description: The sign-in page to redirect to; most clients will process this redirect automatically.
format: url
type: string
'400':
description: 'A bad request; generally, one or more parameters passed in were incorrect or missing. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring.'
schema:
$ref: '#/definitions/SimpleError'
'401':
description: 'The client credentials were invalid (i.e., the `redirect_uri` does not match what we have stored for this client) or the authorization server denied the request. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring.'
schema:
$ref: '#/definitions/SimpleError'
'500':
description: 'There was an unspecified server error. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring.'
schema:
$ref: '#/definitions/SimpleError'
'503':
description: 'The system is undergoing maintenance and we are unable to fulfill this request. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring.'
schema:
$ref: '#/definitions/SimpleError'
summary: Show a web-based login/signup form to a user
tags:
- authorization
/authorization/v2/device:
post:
consumes:
- application/x-www-form-urlencoded
description: |-
This flow should only be used by clients who cannot show a native webview or do not have advanced input controls. It is an alternative to `GET /authorization/v2/authorize`.
Third-party clients will need to use one or the other of these two endpoints, but they will generally not use both.
operationId: generateDeviceCode
parameters:
- description: The client's ID
in: formData
name: client_id
required: true
type: string
- description: The client's secret key
in: formData
name: client_secret
required: true
type: string
- description: A space-separated list of scope(s) requested by the application. Required for all untrusted clients; will be ignored for trusted clients.
in: formData
name: scope
required: false
type: string
produces:
- application/json
responses:
'201':
description: 'We have generated a unique device code and user code. These will only be valid for the amount of time specified in the `expires_in` field; if the user does not complete the login process in that amount of time, the client will need to request a new set of codes.'
schema:
$ref: '#/definitions/DeviceCodeData'
'400':
$ref: '#/responses/Simple400'
'401':
$ref: '#/responses/Simple401'
'500':
$ref: '#/responses/Simple500'
'503':
$ref: '#/responses/Simple503'
summary: Initiate an OAuth2 login flow for limited input devices
tags:
- authorization
/authorization/v2/token:
post:
consumes:
- application/x-www-form-urlencoded
description: |-
Please be aware that the required parameters are contingent on the `grant_type` that you select.
For the `authorization_code` grant type, you are **required** to pass in the `code` and `redirect_uri` parameters. `service`, `username` and `password` parameters will be ignored.
For the `client_credentials` grant type, you do not need to pass in any additional parameters beyond the basic requirements. `code`, `redirect_uri`, `service`, `username` and `password` parameters will be ignored.
For the `device_code` grant type, you are **required** to pass in the `code` parameter. If you are a third-party developer, you are also required to provide the `scope` parameter; see the documentation for `GET /authorization/v2/authorize` for possible values. `redirect_uri`, `service`, `username` and `password` parameters will be ignored.
For the `password` grant type, you are **required** to pass in the `username` and `password` parameters. The `code` and `redirect_uri` parameters are ignored.
Third-party developers do not have access to this grant type.
For the `refresh_token` grant type, you are **required** to pass in the `refresh_token` parameter. The `scope` parameter can optionally be used to request a different set of scopes than were used in the original request, but it **cannot** contain any scopes that were not previously requested. If not specified, then `scope` will be set to whichever scopes were used for the original access token request. If trading in an old non-expiring access token for a refresh-enabled token, set the value of `refresh_token` to the access token value and `token_type_hint` must be set to `access_token`. `code`, `redirect_uri`, `service`, `username` and `password` parameters will be ignored.
The `temporary_user` and `anonymous_user` grant types are custom grant types created by NPR to suit our needs for functionality such as our "try-before-you-buy" experience. If you are a third-party developer, you will not have access to these grant types unless we have explicitly given you permission within our system.
For these grant types, if you are a third-party developer, you are required to provide the `scope` parameter; see the documentation for `GET /authorization/v2/authorize` for possible values. `code`, `redirect_uri`, `service`, `username` and `password` parameters will be ignored.
The `third_party` grant type is another custom grant type created by NPR to handle login via third-party providers such as Facebook and Google. If you are a third-party developer, you will not have access to this grant types unless we have explicitly given you permission within our system.
For this grant type, you are **required** to pass in the `service` and `token` parameters. If you are a third-party developer, you are also required to provide the `scope` parameter; see the documentation for `GET /authorization/v2/authorize` for possible values. The `code` and `redirect_uri` parameters are ignored.
If you are unsure of which grant type to select, assume that `authorization_code` is the one you want.
Note that at this time, refresh tokens are an opt-in feature; however, in the future, they will gradually transition to being opt-out, and ultimately required for all clients. Our general guidance at this time is that if this endpoint starts returning refresh tokens for you, you are responsible for implementing the code to handle them appropriately in accordance with the OAuth 2.0 spec. For more information about our gradual rollout of this feature, please contact the NPR One API team.
operationId: createToken
parameters:
- description: The type of grant the client is requesting
enum:
- authorization_code
- client_credentials
- device_code
- password
- refresh_token
- temporary_user
- anonymous_user
- third_party
in: formData
name: grant_type
required: true
type: string
- description: 'The client''s ID, required for all grant types.'
in: formData
name: client_id
required: true
type: string
- description: 'The client''s secret, required for all grant types.'
in: formData
name: client_secret
required: true
type: string
- description: 'Required for `authorization_code` and `device_code` grant types. The authorization code from a successful call to `/authorization/v2/authorize`, or a device code from a successful call to `/authorization/v2/device`.'
in: formData
name: code
required: false
type: string
- description: Required for `authorization_code` grant type. The requested redirect_uri.
in: formData
name: redirect_uri
required: false
type: string
- description: Required for `password` grant type. The email address of an NPR user.
format: email
in: formData
name: username
required: false
type: string
- description: Required for `password` grant type. The password that matches the user specified with the username parameter.
format: password
in: formData
name: password
required: false
type: string
- description: Required for `third_party` grant type. The name of the third-party login provider.
enum:
- facebook
- google
- microsoft
- janrain
- comcast
in: formData
name: service
required: false
type: string
- description: Required for `refresh_token` grant type. A valid refresh token from a previous successful call to `POST /authorization/v2/token`.
in: formData
name: refresh_token
required: false
type: string
- description: 'Required for third-party developers using the `device_code`, `temporary_user`, and `third_party` grant types. Optionally used by the `refresh_token` grant type. A space-separated list of scope(s) requested by the application.'
in: formData
name: scope
required: false
type: string
- description: 'A hint about the type of the token submitted for a new access and refresh token. If unspecified, the default value is assumed to be `refresh_token`.'
enum:
- access_token
- refresh_token
in: formData
name: token_type_hint
required: false
type: string
produces:
- application/json
responses:
'200':
description: A new token was successfully created
schema:
$ref: '#/definitions/AccessTokenData'
'400':
$ref: '#/responses/Simple400'
'401':
description: 'The client credentials were invalid (any grant type), the user credentials were invalid (`password` grant type), the user has not yet logged in or has purposely denied the request (`device_code` grant type), or the authorization server denied the request.'
schema:
$ref: '#/definitions/SimpleError'
'500':
$ref: '#/responses/Simple500'
'503':
$ref: '#/responses/Simple503'
summary: Create a new OAuth2 access token
tags:
- authorization
/authorization/v2/token/revoke:
post:
consumes:
- application/x-www-form-urlencoded
description: |-
Our implementation follows the proposed IETF specification [RFC-7009](https://tools.ietf.org/html/rfc7009).
If your client application offers the ability to for a logged-in user to log out, and you have access to a long-lived
`client_credentials` token (i.e. you have generated one that you are storing securely for the lifetime of the entire app
install), we suggest (but do not require) that you call this endpoint and revoke the access token belonging to the
logged-in user as part of your logout process. If you do not already have a long-lived `client_credentials` token,
please don't generate one just for the purposes of calling this endpoint.
If you are building a prototype application, we also recommend that you use this endpoint to clean up access tokens
that you generate during the testing of your app and do not intend to reuse.
Note that revoking an access token will automatically revoke any refresh tokens associated with it, and vice-versa.
operationId: revokeToken
parameters:
- description: 'A `client_credentials` access token from the same client application as the token being revoked. Should start with `Bearer`, followed by a space, followed by the token.'
in: header
name: Authorization
required: true
type: string
- description: The access token or refresh token that the client wants to have revoked.
in: formData
name: token
required: true
type: string
- description: 'A hint about the type of the token submitted for revocation. If unspecified, the default value is assumed to be `access_token`.'
enum:
- access_token
- refresh_token
in: formData
name: token_type_hint
required: false
type: string
produces:
- application/json
responses:
'200':
description: The old token was successfully revoked
schema:
description: An empty JSON object
type: object
'400':
$ref: '#/responses/Simple400'
'401':
$ref: '#/responses/Simple401'
'403':
description: The client associated with the access token in the header does not own the access token that this request is attempting to revoke.
schema:
$ref: '#/definitions/SimpleError'
'500':
$ref: '#/responses/Simple500'
'503':
$ref: '#/responses/Simple503'
summary: Revoke an existing OAuth2 access token
tags:
- authorization
/identity/v2/following:
post:
consumes:
- application/json
description: 'After a successful call, this returns a User document with an updated list of affiliations.'
operationId: postFollowing
parameters:
- $ref: '#/parameters/Authorization'
- description: 'A JSON-serialized object which contains data about a user affiliation such as the aggregation ID, affiliation rating, aggregation URL, days since last listen, and following status.'
in: body
name: body
required: true
schema:
$ref: '#/definitions/Affiliation'
responses:
'201':
$ref: '#/responses/IdentitySuccess'
'400':
$ref: '#/responses/400WithDocument'
'401':
$ref: '#/responses/401WithDocument'
'429':
$ref: '#/responses/429WithDocument'
'500':
$ref: '#/responses/500WithDocument'
'503':
$ref: '#/responses/503WithDocument'
security:
- oauth2:
- identity.write
summary: Update the following status of the logged-in user for a particular aggregation
tags:
- identity
/identity/v2/stations:
put:
description: 'Right now, only the primary station can be changed. Previously selected stations will not be deleted, but the new station will be moved to first in the array.'
operationId: updateStations
parameters:
- $ref: '#/parameters/Authorization'
- description: A JSON-serialized array of station IDs
in: body
name: body
required: false
schema:
items:
type: integer
type: array
responses:
'201':
$ref: '#/responses/IdentitySuccess'
'400':
$ref: '#/responses/400WithDocument'
'401':
$ref: '#/responses/401WithDocument'
'429':
$ref: '#/responses/429WithDocument'
'500':
$ref: '#/responses/500WithDocument'
'503':
$ref: '#/responses/503WithDocument'
security:
- oauth2:
- identity.write
summary: Update the logged-in user's favorite station(s)
tags:
- identity
/identity/v2/user:
get:
description: 'After a successful login, the client should send a `GET` call approximately once an hour to refresh the user data.'
operationId: getUser
parameters:
- $ref: '#/parameters/Authorization'
responses:
'200':
$ref: '#/responses/IdentitySuccess'
'401':
$ref: '#/responses/401WithDocument'
'429':
$ref: '#/responses/429WithDocument'
'500':
$ref: '#/responses/500WithDocument'
'503':
$ref: '#/responses/503WithDocument'
security:
- oauth2:
- identity.readonly
summary: Get the latest state information about the logged-in user
tags:
- identity
/identity/v2/user/inherit:
post:
description: |-
This can and should only be used by clients who have access to the `temporary_user` grant type.
Third-party developers do not have access to this grant type by default, and will not need this endpoint.
operationId: inheritFromTempUser
parameters:
- $ref: '#/parameters/Authorization'
- description: The temporary user's ID before the user registered or logged in
in: query
name: temp_user
required: true
type: integer
responses:
'202':
$ref: '#/responses/IdentitySuccess'
'400':
$ref: '#/responses/400WithDocument'
'429':
$ref: '#/responses/429WithDocument'
'500':
$ref: '#/responses/500WithDocument'
'503':
$ref: '#/responses/503WithDocument'
security:
- oauth2:
- identity.write
summary: Copy listening data from a temporary user account to the logged-in user's account
tags:
- identity
'/listening/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:
- description: ID of an aggregation such as a program or podcast
format: int64
in: path
name: aggId
required: true
type: integer
- $ref: '#/parameters/Authorization'
- 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'
format: int32
in: query
name: startNum
required: false
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
schema:
$ref: '#/definitions/AggregationAudioItemListDocument'
'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
tags:
- listening
/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
required: false
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
schema:
$ref: '#/definitions/ChannelsDocument'
'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
/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
'/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:
- description: 'ID of an organization, such as an NPR One station'
format: int64
in: path
name: orgId
required: true
type: integer
- 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
- $ref: '#/parameters/Authorization'
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
schema:
$ref: '#/definitions/OrganizationCategoryAudioListDocument'
'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
'/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:
- description: 'ID of an organization, such as an NPR One station'
format: int64
in: path
name: orgId
required: true
type: integer
- $ref: '#/parameters/Authorization'
responses:
'200':
description: A list of up to three 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
schema:
$ref: '#/definitions/OrganizationOverviewDocument'
'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
/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
/listening/v2/ratings:
post:
consumes:
- application/json
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
required: false
type: boolean
- description: 'A list of RatingData objects which contains data about ratings such as the id of the content, the rating value, elapsed time and more.'
in: body
name: body
required: true
schema:
items:
$ref: '#/definitions/RatingData'
type: array
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
schema:
$ref: '#/definitions/AudioItemListDocument'
'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
/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 `GET /listening/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.
operationId: getRecommendations
parameters:
- $ref: '#/parameters/Authorization'
- $ref: '#/parameters/X-Advertising-ID'
- $ref: '#/parameters/channel'
- 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
required: false
type: string
- 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
required: false
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
/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
schema:
$ref: '#/definitions/SearchListDocument'
'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
/localactivation/v2/donate_email:
get:
description: This will send a station-specific donation email to the logged-in user.
operationId: sendDonationEmail
parameters:
- $ref: '#/parameters/Authorization'
responses:
'200':
description: On success only a blank document
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
schema:
$ref: '#/definitions/CollectionDocument'
'401':
$ref: '#/responses/401WithDocument'
'429':
$ref: '#/responses/429WithDocument'
'500':
$ref: '#/responses/500WithDocument'
security:
- oauth2:
- localactivation
summary: Send a donation email to the logged-in user (only on request)
tags:
- localactivation
/sponsorship/v2/ads:
get:
description: |-
**Not** for use by NPR One clients (for whom sponsorship is already integrated into the Listening Service), this endpoint is designed to be used by our other client applications to request sponsorship on behalf of a user. Sponsorship units are returned in the form of DAAST XML. It is worth noting that this endpoint attempts to always return XML, even in the case of exceptions.
The default behavior of this endpoint is asynchronous; on an initial request, a call to our external sponsorship provider is placed on a queue, which is typically processed within 3 minutes. Once the sponsorship call is received and processed, the returned sponsorship units are placed in a cache on our server for the current user. Subsequent calls to this endpoint will return DAAST sponsorship units from this cache until tracking information is submitted, which removes the ad from the cache and will automatically request additional ads asynchronously if there are fewer than a certain number remaining in the cache.
For development purposes, it's worth noting that there is currently no way to clear a user's cache without submitting some form of tracking.
operationId: getAds
parameters:
- $ref: '#/parameters/Authorization'
- $ref: '#/parameters/X-Advertising-ID'
- description: Whether to force a synchronous call to our external sponsorship provider; the default behavior is asynchronous.
in: query
name: forceResult
required: false
type: boolean
- description: 'How many sponsorship units to request in one call; if left unspecified, the default behavior is to return only 1.'
format: int32
in: query
maximum: 5
minimum: 1
name: adCount
required: false
type: integer
produces:
- application/xml
responses:
'200':
description: 'Request completed successfully; a DAAST XML document is returned. Note that this response will only be returned if either `force=true` was passed in the querystring, or a call to get sponsorship was previously made, and ads now exist in the cache for this user; otherwise, the 202 response is returned.'
schema:
$ref: '#/definitions/DAASTXml'
'202':
description: Request accepted. Check back later for actual ads.
'400':
description: 'A bad request; generally, one or more parameters passed in were incorrect or missing'
schema:
$ref: '#/definitions/ErrorXmlDocument'
'500':
description: A server error
schema:
$ref: '#/definitions/ErrorXmlDocument'
summary: Request DAAST sponsorship units
tags:
- sponsorship
post:
consumes:
- application/json
description: |-
**Not** for use by NPR One clients (for whom sponsorship is already integrated into the Listening Service), this endpoint is designed to be used by our other client applications to submit tracking information for sponsorship units obtained from the `GET /sponsorship/v2/ads` endpoint.
The tracking information should be submitted in the body of the request in the form of a JSON object following the Collection.Doc+JSON specification.
operationId: receiveAdTracking
parameters:
- $ref: '#/parameters/Authorization'
- $ref: '#/parameters/X-Advertising-ID'
- description: A JSON object representing sponsorship tracking data to submit to our external provider.
in: body
name: body
required: true
schema:
$ref: '#/definitions/UserAdDocument'
responses:
'204':
description: 'Request completed successfully, but there is nothing that we need to return to the caller.'
'400':
description: 'A bad request; generally, one or more parameters passed in were incorrect or missing'
schema:
$ref: '#/definitions/Error'
'500':
description: A server error
schema:
$ref: '#/definitions/Error'
summary: Record tracking data for DAAST sponsorship units
tags:
- sponsorship
/stationfinder/v3/stations:
get:
description: |-
This endpoint has two main use cases:
- If no query parameters passed in, it returns a list of stations that are geographically closest to the calling client (based on GeoIP information)
- If one or more query parameters are passed in, it performs a search of NPR stations that match those search criteria (not taking into account the client's physical location)
Clients wanting to implement a 'Change Station' UI should use this endpoint to power their search. In most cases, you'll want to build a search interface that uses one of the 3 provided schemas: `lat` and `lon` (using e.g. the HTML5 Geolocation API), `city` and `state`, _or_ the generic `q` query which can accept a station name, call letters, network name, or zip code. Technically speaking, `q` can also take in either a city name or a state name, but using the `city` and `state` parameters together will yield more accurate geographic search results than `q={cityName}`.
The `lat` and `lon` query parameters should always be passed in together (otherwise the API will return a 400 error), and if included in the query, they will take precedence over any other search criteria; that is, `lat` and `lon` will do a purely geographic search and not take into account `q`, `city` or `state`.
Similarly, `city` and/or `state` will take precedence over (and ignore) `q`.
If clients want to be able to offer multiple types of searches (e.g. 'Search for a station name, city or zipcode') using a *single* search input form, `q` should be used. But again, be aware that using `city` and `state` together will yield more accurate search results than `q={cityName}`.
operationId: searchStations
parameters:
- $ref: '#/parameters/Authorization'
- description: 'Search terms to search on; can be a station name, network name, call letters, or zipcode'
in: query
name: q
required: false
type: string
- description: A city to look for stations from; intended to be paired with `state`
in: query
name: city
pattern: '^[A-Za-z ''\.]+$'
required: false
type: string
- description: A state to look for stations from (using the 2-letter abbreviation); intended to be paired with `city`
in: query
name: state
pattern: '^[A-Z]{2}$'
required: false
type: string
- description: A latitude value from a geographic coordinate system; only works if paired with `lon`
format: float
in: query
name: lat
required: false
type: number
- description: A longitude value from a geographic coordinate system; only works if paired with `lat`
format: float
in: query
name: lon
required: false
type: number
responses:
'200':
description: A list of one or more stations 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
schema:
$ref: '#/definitions/StationListDocument'
'400':
$ref: '#/responses/400WithDocument'
'401':
$ref: '#/responses/401WithDocument'
'429':
$ref: '#/responses/429WithDocument'
'500':
$ref: '#/responses/500WithDocument'
'503':
$ref: '#/responses/503WithDocument'
summary: List stations close to you or filter by search criteria
tags:
- stationfinder
'/stationfinder/v3/stations/{stationId}':
get:
description: |-
This endpoint retrieves information about a given station, based on its numeric ID, which is consistent across all of NPR's APIs.
A typical use case for this data is for clients who want to create a dropdown menu, modal/pop-up or dedicated page displaying more information about the station the client is localized to, including, for example, links to the station's homepage and donation (pledge) page.
operationId: getStationById
parameters:
- $ref: '#/parameters/Authorization'
- description: The numeric ID of a station
format: int64
in: path
name: stationId
required: true
type: integer
responses:
'200':
description: A document describing the station with the given ID
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
schema:
$ref: '#/definitions/StationDocument'
'400':
$ref: '#/responses/400WithDocument'
'401':
$ref: '#/responses/401WithDocument'
'404':
$ref: '#/responses/404WithDocument'
'429':
$ref: '#/responses/429WithDocument'
'500':
$ref: '#/responses/500WithDocument'
'503':
$ref: '#/responses/503WithDocument'
summary: Retrieve metadata for the station with the given numeric ID
tags:
- stationfinder
definitions:
AbstractCDocLink:
allOf:
- $ref: '#/definitions/AbstractLink'
- properties:
content-type:
description: The MIME type of the response of this link
type: string
required:
- content-type
AbstractLink:
properties:
href:
description: The link to be followed
format: uri
type: string
required:
- href
AccessTokenData:
properties:
access_token:
description: The access token to use for all future calls
type: string
expires_in:
description: The remaining lifetime of the access token (in seconds)
format: int32
type: integer
refresh_token:
description: 'The refresh token that can be used to obtain a new access token if the old one expires; if a refresh token is returned, it is the client''s responsibility to securely cache it for future use.'
type: string
token_type:
description: 'Identifies the type of token returned. At this time, this field always has the value `Bearer`.'
enum:
- Bearer
- MAC
type: string
required:
- access_token
- token_type
- expires_in
AdTrackingData:
description: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider
properties:
adId:
description: 'The DAAST Ad node `id` attribute value, (e.g. AdswizzAd12345)'
type: string
event:
default: start
description: The user-interaction event to submit tracking for
enum:
- start
- firstQuartile
- midpoint
- thirdQuartile
- complete
type: string
required:
- adId
- event
AdTrackingDocument:
allOf:
- $ref: '#/definitions/CollectionDocument'
- properties:
attributes:
$ref: '#/definitions/AdTrackingData'
description: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider
items:
description: Not used
items:
type: 'null'
type: array
description: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider
AdXml:
properties:
InLine:
$ref: '#/definitions/InLineXml'
id:
type: string
xml:
attribute: true
type: object
xml:
name: Ad
namespace: 'http://www.w3.org/2001/XMLSchema-instance'
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
AggregationAudioItemListDocument:
allOf:
- $ref: '#/definitions/CollectionDocument'
- properties:
attributes:
$ref: '#/definitions/AggregationData'
description: The metadata which describes the aggregation
items:
description: An array of Audio Items (recommendations)
items:
$ref: '#/definitions/AudioItemDocument'
type: array
links:
$ref: '#/definitions/AggregationLinks'
description: An array of links for the aggregation. Look here for images associated with the aggregation or for a more link to get more episodes.
description: An array of audio recommendations with additional metadata about the aggregation they are associated with
AggregationData:
properties:
affiliation:
description: A unique identifier for the aggregation
type: string
affiliationMeta:
$ref: '#/definitions/Affiliation'
description: Metadata about the logged-in user's relationship to this aggregation
description:
description: A short description or teaser
type: string
station:
default: NPR
description: The producer of this aggregation
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 resultsContributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.