News

API: Internal/Beta

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 useCommon
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: TypeScript
// Authenticated as admin
await callAPI(NewsApi.newPost(
    {
        "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
    }
);

/*
{
}
*/
await callAPI(NewsApi.listPosts(
    {
        "filter": null,
        "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"
        }
    ]
}
*/
await callAPI(NewsApi.updatePost(
    {
        "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"
    }
);

/*
{
}
*/
await callAPI(NewsApi.deletePost(
    {
        "id": 4512
    }
);

/*
{
}
*/
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 useCommon
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: TypeScript
// Authenticated as admin
await callAPI(NewsApi.newPost(
    {
        "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
    }
);

/*
{
}
*/
await callAPI(NewsApi.listPosts(
    {
        "filter": null,
        "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"
        }
    ]
}
*/
await callAPI(NewsApi.togglePostHidden(
    {
        "id": 4512
    }
);

/*
{
}
*/
await callAPI(NewsApi.listPosts(
    {
        "filter": null,
        "withHidden": false,
        "page": 0,
        "itemsPerPage": 50
    }
);

/*
{
    "itemsInTotal": 0,
    "itemsPerPage": 50,
    "pageNumber": 0,
    "items": [
    ]
}
*/
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

API: Internal/Beta Auth: Authenticated

Retrieves a concrete post by ID

Request Response Error
GetPostByIdRequest NewsPost CommonErrorMessage

listCategories

API: Internal/Beta Auth: Authenticated

Lists all news categories in UCloud

Request Response Error
Unit List<String> CommonErrorMessage

listDowntimes

API: Internal/Beta Auth: Public

Retrieves a page of news related to upcoming downtime

Request Response Error
Unit Page<NewsPost> CommonErrorMessage

listPosts

API: Internal/Beta Auth: Public

Retrieves a page of news

Request Response Error
ListPostsRequest Page<NewsPost> CommonErrorMessage

deletePost

API: Internal/Beta Auth: Admin

Deletes an existing post

Request Response Error
DeleteNewsPostRequest Unit CommonErrorMessage

newPost

API: Internal/Beta Auth: Admin

Creates a new post

Request Response Error
NewPostRequest Unit CommonErrorMessage

togglePostHidden

API: Internal/Beta Auth: Admin

Swaps the visibility state of an existing post

Request Response Error
TogglePostHiddenRequest Unit CommonErrorMessage

updatePost

API: Internal/Beta Auth: Admin

Updates an existing post

Request Response Error
UpdatePostRequest Unit CommonErrorMessage

Data Models

NewsPost

API: Internal/Beta

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

API: Internal/Beta

data class DeleteNewsPostRequest(
    val id: Long,
)
Properties
id: Long

GetPostByIdRequest

API: Internal/Beta

data class GetPostByIdRequest(
    val id: Long,
)
Properties
id: Long

ListPostsRequest

API: Internal/Beta

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

API: Internal/Beta

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

API: Internal/Beta

data class TogglePostHiddenRequest(
    val id: Long,
)
Properties
id: Long

UpdatePostRequest

API: Internal/Beta

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