API docs by Redocly

Personalised News Aggregator API (1.0.0)

Download OpenAPI specification:

Articles

List articles

Returns a paginated list of articles, optionally filtered by source, topic, and/or search query

query Parameters
sourceId
string

Filter by source ID

sourceIds
Array of strings

Filter to a set of source IDs (e.g. a caller's subscribed sources), so pagination totals are computed post-filter instead of requiring the caller to filter results client-side

topicId
string

Filter by topic ID

q
string

Case-insensitive search in headline and snippet

required
object (Pageable)

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "empty": true,
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "pageable": {
    },
  • "size": 0,
  • "sort": {
    },
  • "totalElements": 0,
  • "totalPages": 0
}

Batch-get articles by IDs

Returns articles matching the provided list of IDs, useful for fetching a user's saved articles

Authorizations:
bearer-jwt
Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • {
    }
]

Get full article

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "author": "string",
  • "body": [
    ],
  • "externalUrl": "string",
  • "fetchedAt": "2019-08-24T14:15:22Z",
  • "headline": "string",
  • "id": "string",
  • "imageUrl": "string",
  • "publishedAt": "2019-08-24T14:15:22Z",
  • "readingMinutes": 0,
  • "snippet": "string",
  • "sourceId": "string",
  • "topicId": "string"
}

Sources

List all RSS sources

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Submit a new RSS feed URL

Adds a new RSS source. If the URL already exists, returns the existing source.

Authorizations:
bearer-jwt
Request Body schema: application/json
required
name
required
string non-empty
rssUrl
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "rssUrl": "string"
}

Response samples

Content type
application/json
{
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "fetchError": "string",
  • "fetchStatus": "PENDING",
  • "id": "string",
  • "initials": "string",
  • "lastFetchedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "rssUrl": "string",
  • "subscriberCount": 0
}

Get source details

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "fetchError": "string",
  • "fetchStatus": "PENDING",
  • "id": "string",
  • "initials": "string",
  • "lastFetchedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "rssUrl": "string",
  • "subscriberCount": 0
}

Register a subscription to a source

Increments the source's subscriber count. Intended for service-to-service use by user-service when a user subscribes.

Authorizations:
bearer-jwt
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "fetchError": "string",
  • "fetchStatus": "PENDING",
  • "id": "string",
  • "initials": "string",
  • "lastFetchedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "rssUrl": "string",
  • "subscriberCount": 0
}

Remove a subscription from a source

Decrements the source's subscriber count; the source is deleted once the count reaches zero. Intended for service-to-service use by user-service.

Authorizations:
bearer-jwt
path Parameters
id
required
string

Responses

Topics

List all topics

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Authentication

Authenticate and obtain a JWT

Request Body schema: application/json
required
password
required
string non-empty
username
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "token": "string"
}

Register a new user

Creates a new user account. The OAuth2 token endpoint at /oauth2/token handles login.

Request Body schema: application/json
required
email
required
string <email> non-empty
name
string
password
required
string [ 8 .. 2147483647 ] characters
username
required
string [ 3 .. 50 ] characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "name": "string",
  • "password": "stringst",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "avatarInitials": "string",
  • "email": "string",
  • "id": "string",
  • "name": "string",
  • "username": "string"
}

Users

Get current user profile

Authorizations:
bearer-jwt

Responses

Response samples

Content type
application/json
{
  • "avatarInitials": "string",
  • "email": "string",
  • "id": "string",
  • "name": "string",
  • "username": "string"
}

Update current user profile

Authorizations:
bearer-jwt
Request Body schema: application/json
required
email
string <email>
name
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "avatarInitials": "string",
  • "email": "string",
  • "id": "string",
  • "name": "string",
  • "username": "string"
}

Remove a saved article for the current user

Atomically removes the article from the user's saved list.

Authorizations:
bearer-jwt
path Parameters
articleId
required
string

Responses

Response samples

Content type
application/json
{
  • "enabledSourceIds": [
    ],
  • "savedArticleIds": [
    ],
  • "selectedTopicIds": [
    ]
}

Save an article for the current user

Atomically adds the article to the user's saved list.

Authorizations:
bearer-jwt
path Parameters
articleId
required
string

Responses

Response samples

Content type
application/json
{
  • "enabledSourceIds": [
    ],
  • "savedArticleIds": [
    ],
  • "selectedTopicIds": [
    ]
}

Get current user settings

Returns user preferences: selected topics, enabled sources, and saved article IDs

Authorizations:
bearer-jwt

Responses

Response samples

Content type
application/json
{
  • "enabledSourceIds": [
    ],
  • "savedArticleIds": [
    ],
  • "selectedTopicIds": [
    ]
}

Update current user settings

Authorizations:
bearer-jwt
Request Body schema: application/json
required
enabledSourceIds
Array of strings
savedArticleIds
Array of strings
selectedTopicIds
Array of strings

Responses

Request samples

Content type
application/json
{
  • "enabledSourceIds": [
    ],
  • "savedArticleIds": [
    ],
  • "selectedTopicIds": [
    ]
}

Response samples

Content type
application/json
{
  • "enabledSourceIds": [
    ],
  • "savedArticleIds": [
    ],
  • "selectedTopicIds": [
    ]
}

Unsubscribe the current user from a source

Removes the source from the user's enabled sources and decrements the shared subscriber count in content-service (the source is removed there once nobody is subscribed).

Authorizations:
bearer-jwt
path Parameters
sourceId
required
string

Responses

Response samples

Content type
application/json
{
  • "enabledSourceIds": [
    ],
  • "savedArticleIds": [
    ],
  • "selectedTopicIds": [
    ]
}

Subscribe the current user to a source

Adds the source to the user's enabled sources and increments the shared subscriber count in content-service.

Authorizations:
bearer-jwt
path Parameters
sourceId
required
string

Responses

Response samples

Content type
application/json
{
  • "enabledSourceIds": [
    ],
  • "savedArticleIds": [
    ],
  • "selectedTopicIds": [
    ]
}