News

News communicates to users about new features, bug fixes and upcoming maintenance.

Rationale

Only administrators of UCloud can create news posts. All posts are publicly readable.

Administrators can view hidden posts using withHidden = true. This flag is not usable by normal users.

Table of Contents

1. Examples

Description
News CRUD
Making a news post as hidden

2. Remote Procedure Calls

Name	Description
getPostBy	Retrieves a concrete post by ID
listCategories	Lists all news categories in UCloud
listDowntimes	Retrieves a page of news related to upcoming downtime
listPosts	Retrieves a page of news
deletePost	Deletes an existing post
newPost	Creates a new post
togglePostHidden	Swaps the visibility state of an existing post
updatePost	Updates an existing post

3. Data Models

Name	Description
NewsPost	No description
DeleteNewsPostRequest	No description
GetPostByIdRequest	No description
ListPostsRequest	No description
NewPostRequest	No description
TogglePostHiddenRequest	No description
UpdatePostRequest	No description

Example: News CRUD

Frequency of use	Common
Actors	UCloud Admin (admin)

Communication Flow: Kotlin

News.newPost.call(
    NewPostRequest(
        body = "Et ipsam ex explicabo quis aut sit voluptates.", 
        category = "News", 
        hideFrom = null, 
        showFrom = 0, 
        subtitle = "Short summary of the post", 
        title = "This is a news post", 
    ),
    admin
).orThrow()

/*
Unit
*/
News.listPosts.call(
    ListPostsRequest(
        filter = null, 
        itemsPerPage = 50, 
        page = 0, 
        withHidden = false, 
    ),
    admin
).orThrow()

/*
Page(
    items = listOf(NewsPost(
        body = "Et ipsam ex explicabo quis aut sit voluptates.", 
        category = "News", 
        hidden = false, 
        hideFrom = null, 
        id = 4512, 
        postedBy = "UCloud Admin", 
        showFrom = 0, 
        subtitle = "Short summary of the post", 
        title = "This is a news post", 
    )), 
    itemsInTotal = 1, 
    itemsPerPage = 50, 
    pageNumber = 0, 
)
*/
News.updatePost.call(
    UpdatePostRequest(
        body = "Et ipsam ex explicabo quis aut sit voluptates.", 
        category = "News", 
        hideFrom = null, 
        id = 4512, 
        showFrom = 0, 
        subtitle = "Short summary of the post", 
        title = "Updated title", 
    ),
    admin
).orThrow()

/*
Unit
*/
News.deletePost.call(
    DeleteNewsPostRequest(
        id = 4512, 
    ),
    admin
).orThrow()

/*
Unit
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as admin
curl -XPUT -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/news/post" -d '{
    "title": "This is a news post",
    "subtitle": "Short summary of the post",
    "body": "Et ipsam ex explicabo quis aut sit voluptates.",
    "showFrom": 0,
    "category": "News",
    "hideFrom": null
}'


# {
# }

curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/news/list?withHidden=false&page=0&itemsPerPage=50" 

# {
#     "itemsInTotal": 1,
#     "itemsPerPage": 50,
#     "pageNumber": 0,
#     "items": [
#         {
#             "id": 4512,
#             "title": "This is a news post",
#             "subtitle": "Short summary of the post",
#             "body": "Et ipsam ex explicabo quis aut sit voluptates.",
#             "postedBy": "UCloud Admin",
#             "showFrom": 0,
#             "hideFrom": null,
#             "hidden": false,
#             "category": "News"
#         }
#     ]
# }

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/news/update" -d '{
    "id": 4512,
    "title": "Updated title",
    "subtitle": "Short summary of the post",
    "body": "Et ipsam ex explicabo quis aut sit voluptates.",
    "showFrom": 0,
    "hideFrom": null,
    "category": "News"
}'


# {
# }

curl -XDELETE -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/news/delete" -d '{
    "id": 4512
}'


# {
# }

Communication Flow: Visual

Example: Making a news post as hidden

Frequency of use	Common
Actors	UCloud Admin (admin)

Communication Flow: Kotlin

News.newPost.call(
    NewPostRequest(
        body = "Et ipsam ex explicabo quis aut sit voluptates.", 
        category = "News", 
        hideFrom = null, 
        showFrom = 0, 
        subtitle = "Short summary of the post", 
        title = "This is a news post", 
    ),
    admin
).orThrow()

/*
Unit
*/
News.listPosts.call(
    ListPostsRequest(
        filter = null, 
        itemsPerPage = 50, 
        page = 0, 
        withHidden = false, 
    ),
    admin
).orThrow()

/*
Page(
    items = listOf(NewsPost(
        body = "Et ipsam ex explicabo quis aut sit voluptates.", 
        category = "News", 
        hidden = false, 
        hideFrom = null, 
        id = 4512, 
        postedBy = "UCloud Admin", 
        showFrom = 0, 
        subtitle = "Short summary of the post", 
        title = "This is a news post", 
    )), 
    itemsInTotal = 1, 
    itemsPerPage = 50, 
    pageNumber = 0, 
)
*/
News.togglePostHidden.call(
    TogglePostHiddenRequest(
        id = 4512, 
    ),
    admin
).orThrow()

/*
Unit
*/
News.listPosts.call(
    ListPostsRequest(
        filter = null, 
        itemsPerPage = 50, 
        page = 0, 
        withHidden = false, 
    ),
    admin
).orThrow()

/*
Page(
    items = emptyList(), 
    itemsInTotal = 0, 
    itemsPerPage = 50, 
    pageNumber = 0, 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as admin
curl -XPUT -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/news/post" -d '{
    "title": "This is a news post",
    "subtitle": "Short summary of the post",
    "body": "Et ipsam ex explicabo quis aut sit voluptates.",
    "showFrom": 0,
    "category": "News",
    "hideFrom": null
}'


# {
# }

curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/news/list?withHidden=false&page=0&itemsPerPage=50" 

# {
#     "itemsInTotal": 1,
#     "itemsPerPage": 50,
#     "pageNumber": 0,
#     "items": [
#         {
#             "id": 4512,
#             "title": "This is a news post",
#             "subtitle": "Short summary of the post",
#             "body": "Et ipsam ex explicabo quis aut sit voluptates.",
#             "postedBy": "UCloud Admin",
#             "showFrom": 0,
#             "hideFrom": null,
#             "hidden": false,
#             "category": "News"
#         }
#     ]
# }

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/news/toggleHidden" -d '{
    "id": 4512
}'


# {
# }

curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/news/list?withHidden=false&page=0&itemsPerPage=50" 

# {
#     "itemsInTotal": 0,
#     "itemsPerPage": 50,
#     "pageNumber": 0,
#     "items": [
#     ]
# }

Communication Flow: Visual

Remote Procedure Calls

getPostBy

Retrieves a concrete post by ID

Request	Response	Error
GetPostByIdRequest	NewsPost	CommonErrorMessage

listCategories

Lists all news categories in UCloud

Request	Response	Error
Unit	List<String>	CommonErrorMessage

listDowntimes

Retrieves a page of news related to upcoming downtime

Request	Response	Error
Unit	Page<NewsPost>	CommonErrorMessage

listPosts

Retrieves a page of news

Request	Response	Error
ListPostsRequest	Page<NewsPost>	CommonErrorMessage

deletePost

Deletes an existing post

Request	Response	Error
DeleteNewsPostRequest	Unit	CommonErrorMessage

newPost

Creates a new post

Request	Response	Error
NewPostRequest	Unit	CommonErrorMessage

togglePostHidden

Swaps the visibility state of an existing post

Request	Response	Error
TogglePostHiddenRequest	Unit	CommonErrorMessage

updatePost

Updates an existing post

Request	Response	Error
UpdatePostRequest	Unit	CommonErrorMessage

Data Models

NewsPost

data class NewsPost(
    val id: Long,
    val title: String,
    val subtitle: String,
    val body: String,
    val postedBy: String,
    val showFrom: Long,
    val hideFrom: Long?,
    val hidden: Boolean,
    val category: String,
)

Properties

id: Long

title: String

subtitle: String

body: String

postedBy: String

showFrom: Long

hideFrom: Long?

hidden: Boolean

category: String

---

DeleteNewsPostRequest

data class DeleteNewsPostRequest(
    val id: Long,
)

Properties

id: Long

---

GetPostByIdRequest

data class GetPostByIdRequest(
    val id: Long,
)

Properties

id: Long

---

ListPostsRequest

data class ListPostsRequest(
    val filter: String?,
    val withHidden: Boolean,
    val page: Int,
    val itemsPerPage: Int,
)

Properties

filter: String?

withHidden: Boolean

page: Int

itemsPerPage: Int

---

NewPostRequest

data class NewPostRequest(
    val title: String,
    val subtitle: String,
    val body: String,
    val showFrom: Long,
    val category: String,
    val hideFrom: Long?,
)

Properties

title: String

subtitle: String

body: String

showFrom: Long

category: String

hideFrom: Long?

---

TogglePostHiddenRequest

data class TogglePostHiddenRequest(
    val id: Long,
)

Properties

id: Long

---

UpdatePostRequest

data class UpdatePostRequest(
    val id: Long,
    val title: String,
    val subtitle: String,
    val body: String,
    val showFrom: Long,
    val hideFrom: Long?,
    val category: String,
)

Properties

id: Long

title: String

subtitle: String

body: String

showFrom: Long

hideFrom: Long?

category: String

---