rpc_http

« Previous section Next section »

UCloud Developer Guide / Developing UCloud / Micro Library Reference / RPC / RPC HTTP

RPC HTTP

Configures the HTTP backend for this call.

Fields	Mandatory	Description
method	❌ No Default: HttpMethod.GET	HTTP method used for this call
path	✅ Yes	Configures the path segment of the URL, i.e. where this call should listen
params	❌ No	Configures the parameters segment of the URL
headers	❌ No	Configures how HTTP Request headers affect this request
body	❌ No	Configures how HTTP request body affect this request

path

Defines how the message should be parsed from the path.

Function	Description
using(baseContext: String)	Defines the path prefix, commonly used to define a shared prefix in a call description container
+"segment"	Adds a new fixed path segment
+boundTo(prop)	binds the value to prop

params

Defines how the message should be parsed from the URL parameters.

Function	Description
+boundTo(prop)	Binds to a parameter (called by the exact name of the property)

headers

Defines how the message should be parsed from the HTTP request headers.

Function	Description
+("Header" to "Value")	Requires the "Header" to have a fixed value of "Value"
+"Header"	Requires the "Header" to be present (any value accepted)
+boundTo(header: String, prop)	Binds the header to prop

Note: When using the boundTo() function, header values will be serialized and deserialized as Base64. This is done to ensure that any value can be put into the header safely.

body

Defines how the message should be parsed from the HTTP request body. At the moment this will only read JSON messages.

Function	Description
bindEntireRequestFromBody()	Reads the full request type via the body
bindToSubProperty(prop)	Reads the request body and binds it to a sub-property of the request type

Examples

Example: POST request with entire request in body

http {
    method = HttpMethod.Post

    path {
        using(baseContext) // baseContext = "/api/avatar"
        +"update"
    }

    body { bindEntireRequestFromBody() }
}

The above RPC will listen on POST /api/avatar/update.

Example: GET request with pagination

/*
data class ListActivityByPathRequest(
    val path: String,
    override val itemsPerPage: Int?,
    override val page: Int?
) : WithPaginationRequest
*/

http {
    path {
        using(baseContext)
        +"by-path"
    }

    params {
        +boundTo(ListActivityByPathRequest::itemsPerPage)
        +boundTo(ListActivityByPathRequest::page)
        +boundTo(ListActivityByPathRequest::path)
    }
}

Example: File upload with metadata passed in headers

/*
data class UploadApplicationLogoRequest(
    val name: String,
    val data: BinaryStream
)
*/

http {
    method = HttpMethod.Post

    path {
        using(baseContext)
        +"uploadLogo"
    }

    headers {
        +boundTo("Upload-Name", UploadApplicationLogoRequest::name)
    }

    body {
        bindToSubProperty(UploadApplicationLogoRequest::data)
    }
}

Example: Reading parameters from the path segment

/*
data class FindByStringId(val id: String)
*/

http {
    method = HttpMethod.Get

    path {
        using(baseContext)
        +"lookup"
        +boundTo(FindByStringId::id)
    }
}