⚙︎ CoreArticleService

Core service to either query a single article (rpc GetArticle()) identified by its id or to query multiple articles (rpc ListArticles()) by providing a query.

All results returned from this service are unfiltered by default, hence they may contain elements that are expired, not yet valid or whose state is not PUBLISHED. This behaviour can be changed by providing a RequestSettings object.

service ArticleService {
rpc GetArticle(GetArticleRequest) returns (stroeer.core.v1.Article) {}
rpc BatchGetArticles(BatchGetArticlesRequest) returns (BatchGetArticlesResponse) {}
rpc ListArticles(ListArticlesRequest) returns (ListArticlesResponse) {}
// Allow Empty as request param
// buf:lint:ignore RPC_REQUEST_STANDARD_NAME
rpc ListSections(google.protobuf.Empty) returns (ListSectionsResponse) {}
}

[~]

⚙︎ GetArticle

rpc GetArticle (GetArticleRequest) returns (stroeer.core.v1.Article) {}

returns a single stroeer.core.v1.Article if the given id exists, an Error, otherwise. (todo: describe errors)

message GetArticleRequest {
int64 id = 1;
RequestSettings request_settings = 2;
}

[~]

⚙︎ BatchGetArticle

returns multiple stroeer.core.v1.Article for the given ids. The ordering of items will the same ordering as the ids requested. If an id does not exists, it is omitted in the result (no error will be raised).

There is a maximum of 100 items that can be queried in one batch.

message BatchGetArticlesRequest {
repeated int64 ids = 1;
RequestSettings request_settings = 2;
}

[~]

returns a message-listarticlesresponse with articles matching the query. If the results exceed 100 Articles or 1 MB the response can be paginated to obtain additional results.

ListArticlesRequest

message ListArticlesRequest {
Query query = 1;
Filters filters = 2;
int32 page_size = 3;
string page_token = 4;
RequestSettings request_settings = 5;

[~]

Query

Specify the search criteria. The list-API is build around sections which come in two flavors:

1. home_section: find all articles that resides within that exact section. The home_section is equal to the settings found in the CMS, e.g. /nachrichten/wissen/
2. root_section: this property is derived from the home_section path by retaining only the root folder, e.g. for /nachrichten/wissen/ the root_section becomes /nachrichten/

In most cases using the root_section should yield better results since it will also find content in nested sections whereas home_section would only return content which was curated into the exact section that was queried.

message Query {
string path = 1;
Type type = 2;
SortBy sort_by = 3;
Order order = 4;
google.protobuf.Timestamp from_time = 5;
google.protobuf.Timestamp to_time = 6;

[~]

Type

see the description above why these query types exist, also see Reference how section information are stored.

enum Type {
TYPE_UNSPECIFIED = 0;
HOME_SECTION = 1;
ROOT_SECTION = 2;
}

[~]

SortBy

enum SortBy {
SORT_BY_UNSPECIFIED = 0;
UPDATE_TIME = 1;
PUBLISH_TIME = 2;
}

[~]

Order

order of index traversal, default: ascending.

enum Order {
ORDER_UNSPECIFIED = 0;
ASCENDING = 1;
DESCENDING = 2;
}

[~]

Filters

If you need to further refine the Query results, you can optionally provide a filter expression. A filter expression determines which items within the Query results should be returned to you. All of the other results are discarded.

A filter expression is applied after a Query finishes, but before the results are returned. Therefore, a Query consumes the same amount of read capacity, regardless of whether a filter expression is present.

message Filters {
repeated Article.Type type_includes = 1;
repeated Article.Type type_excludes = 2;
repeated Article.SubType sub_type_includes = 3;
repeated Article.SubType sub_type_excludes = 4;
}

[~]

RequestSettings

Alters the behavior of the request in a way that filters or alters the result or parts of the result based on validity of the article or its elements.

You can also alter the view mode of the article, selecting either the full article or a limited version of it (called teaser or trail)

RequestSettings.ArticleViewMode

RequestSettings.ArticleValidity

RequestSettings.ElementValidity

message RequestSettings {
ArticleViewMode article_view_mode = 1;
ArticleValidity article_validity = 2;
ElementValidity element_validity = 3;

enum ArticleViewMode {
ARTICLE_VIEW_MODE_UNSPECIFIED = 0;
ARTICLE_VIEW_MODE_DEFAULT = 1;
ARTICLE_VIEW_MODE_TEASER = 2;
}

enum ArticleValidity {
ARTICLE_VALIDITY_UNSPECIFIED = 0;
ARTICLE_VALIDITY_VALID = 1;
ARTICLE_VALIDITY_IGNORE = 2;
}

enum ElementValidity {
ELEMENT_VALIDITY_UNSPECIFIED = 0;
ELEMENT_VALIDITY_VALID = 1;
ELEMENT_VALIDITY_IGNORE = 2;
}
}

[~]

ListArticlesResponse

message ListArticlesResponse {
repeated stroeer.core.v1.Article articles = 1;
string next_page_token = 2;
}

[~]

⚙︎ ListSections

list the available root sections

ListSectionsResponse

list all available root_sections that can be used in the query above.

message ListSectionsResponse {
repeated string sections = 1;
}

[~]

[~]