ballerina.net.http package

public struct HeaderValue

Represents an HTTP header value

Field Name Data Type Description Default Value
value string The value of header
param map The param map of header

public struct HttpConnectorError

HttpConnectorError struct represents an error occured during the HTTP client invocation

Field Name Data Type Description Default Value
msg string An error message explaining about the error
cause error The error that caused HttpConnectorError to get thrown
stackTrace StackFrame[] Represents the invocation stack when HttpConnectorError is thrown
statusCode int HTTP status code

public struct Options

Options struct represents options to be used for HTTP client invocation

Field Name Data Type Description Default Value
port int Port number of the remote service
endpointTimeout int Endpoint timeout value in millisecond (default value: 60000 milliseconds) 60000
maxActiveConnections int The maximum number of active connections the connector can create (default value: -1, indicates that the number of connections is not restricted) -1
keepAlive boolean Keep the connection or close it (default value: true) true
transferEncoding string The types of encoding applied to the request (default value: chunking) chunking
chunking string The chunking behaviour of the request auto
httpVersion string The version of HTTP outbound request
followRedirects FollowRedirects Redirect related options
ssl SSL SSL/TLS related options
retryConfig Retry Retry related options
proxy Proxy Proxy server related options

public struct Request

Represents an HTTP request message

Field Name Data Type Description Default Value
remoteHost string host: The server host name
port int The server port
path string Resource path of request URI
method string HTTP request method
httpVersion string The version of HTTP
userAgent string User-Agent request header
restUriPostFix string host: The server host name
headers map Request headers

  • < Request > addHeader ( string headerName , string headerValue )

    Adds the specified key/value pair as an HTTP header to the request

    Parameter Name Data Type Description
    headerName string The header name
    headerValue string The header value

  • < Request > createSessionIfAbsent ( ) ( Session )

    Gets the Session struct for a valid session cookie from the request. Otherwise creates a new Session struct.

    Return Variable Data Type Description
    Session

  • < Request > expects100Continue ( ) ( boolean )

    Checks whether the client expects a 100-continue response.

    Return Variable Data Type Description
    boolean

  • < Request > getBinaryPayload ( ) ( blob )

    Gets the request payload in blob format

    Return Variable Data Type Description
    blob

  • < Request > getContentLength ( ) ( int )

    Gets the Content-Length header from the request

    Return Variable Data Type Description
    int

  • < Request > getFormParams ( ) ( map )

    Gets the form parameters from the HTTP request as a map

    Return Variable Data Type Description
    map

  • < Request > getHeader ( string headerName ) ( HeaderValue )

    Gets a transport header from the request

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    HeaderValue

  • < Request > getHeaders ( string headerName ) ( HeaderValue[] )

    Gets transport headers from the request

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    HeaderValue[]

  • < Request > getJsonPayload ( ) ( json )

    Gets the request payload in JSON format

    Return Variable Data Type Description
    json

  • < Request > getMethod ( ) ( string )

    Gets the HTTP method from the request

    Return Variable Data Type Description
    string

  • < Request > getProperty ( string propertyName ) ( string )

    Retrieves the named property from the request

    Parameter Name Data Type Description
    propertyName string The name of the property

    Return Variable Data Type Description
    string

  • < Request > getQueryParams ( ) ( map )

    Gets the query parameters from the HTTP request as a map

    Return Variable Data Type Description
    map

  • < Request > getRequestURL ( ) ( string )

    Gets the request URL from the request

    Return Variable Data Type Description
    string

  • < Request > getSession ( ) ( Session )

    Gets the Session struct from the request if it is present

    Return Variable Data Type Description
    Session

  • < Request > getStringPayload ( ) ( string )

    Gets the request payload as a string

    Return Variable Data Type Description
    string

  • < Request > getXmlPayload ( ) ( xml )

    Gets the request payload in XML format

    Return Variable Data Type Description
    xml

  • < Request > removeAllHeaders ( )

    Removes all transport headers from the message

  • < Request > removeHeader ( string key )

    Removes a transport header from the request

    Parameter Name Data Type Description
    key string The header name

  • < Request > setBinaryPayload ( blob payload )

    Sets a blob as the request payload

    Parameter Name Data Type Description
    payload blob The blob representation of the message payload

  • < Request > setHeader ( string headerName , string headerValue )

    Sets the value of a transport header

    Parameter Name Data Type Description
    headerName string The header name
    headerValue string The header value

  • < Request > setJsonPayload ( json payload )

    Sets a JSON as the request payload

    Parameter Name Data Type Description
    payload json The JSON payload to be

  • < Request > setProperty ( string propertyName , string propertyValue )

    Sets a request property

    Parameter Name Data Type Description
    propertyName string The name of the property
    propertyValue string The value of the property

  • < Request > setStringPayload ( string payload )

    Sets a string as the request payload

    Parameter Name Data Type Description
    payload string The payload to be set to the request as a string

  • < Request > setXmlPayload ( xml payload )

    Sets an XML as the payload

    Parameter Name Data Type Description
    payload xml The XML payload object

public struct Response

Represents an HTTP response message

Field Name Data Type Description Default Value
statusCode int The response status code
reasonPhrase string The status code reason phrase
server string The server header
headers map Response headers

  • < Response > addHeader ( string headerName , string headerValue )

    Adds the specified key/value pair as an HTTP header to the response

    Parameter Name Data Type Description
    headerName string The header name
    headerValue string The header value

  • < Response > forward ( Response resp ) ( HttpConnectorError )

    Forwards client service response directly to the caller.

    Parameter Name Data Type Description
    resp Response The new instance of the response message

    Return Variable Data Type Description
    HttpConnectorError

  • < Response > getBinaryPayload ( ) ( blob )

    Gets the response payload in blob format

    Return Variable Data Type Description
    blob

  • < Response > getContentLength ( ) ( int )

    Gets the length of the response payload, as given in the Content-Length header of the response

    Return Variable Data Type Description
    int

  • < Response > getHeader ( string headerName ) ( HeaderValue )

    Gets the named HTTP header from the response

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    HeaderValue

  • < Response > getHeaders ( string headerName ) ( HeaderValue[] )

    Gets the HTTP headers from the response

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    HeaderValue[]

  • < Response > getJsonPayload ( ) ( json )

    Gets the response payload in JSON format

    Return Variable Data Type Description
    json

  • < Response > getProperty ( string propertyName ) ( string )

    Retrieve a response property

    Parameter Name Data Type Description
    propertyName string The name of the property

    Return Variable Data Type Description
    string

  • < Response > getStatusCode ( ) ( int )

    Gets the HTTP status code from the response

    Return Variable Data Type Description
    int

  • < Response > getStringPayload ( ) ( string )

    Gets the response payload as a string

    Return Variable Data Type Description
    string

  • < Response > getXmlPayload ( ) ( xml )

    Gets the response payload in XML format

    Return Variable Data Type Description
    xml

  • < Response > removeAllHeaders ( )

    Removes all transport headers from the response

  • < Response > removeHeader ( string key )

    Removes a transport header from the response

    Parameter Name Data Type Description
    key string The header name

  • < Response > send ( ) ( HttpConnectorError )

    Sends outbound response to the caller.

    Return Variable Data Type Description
    HttpConnectorError

  • < Response > send100Continue ( ) ( HttpConnectorError )

    Sends a 100-continue response to the client.

    Return Variable Data Type Description
    HttpConnectorError

  • < Response > setBinaryPayload ( blob payload )

    Sets a blob as the response payload

    Parameter Name Data Type Description
    payload blob The blob representation of the message payload

  • < Response > setHeader ( string key , string value )

    Sets the value of a transport header

    Parameter Name Data Type Description
    key string The header name
    value string The header value

  • < Response > setJsonPayload ( json payload )

    Sets a JSON as the response payload

    Parameter Name Data Type Description
    payload json The JSON payload object

  • < Response > setProperty ( string propertyName , string propertyValue )

    Sets a response property

    Parameter Name Data Type Description
    propertyName string The name of the property
    propertyValue string The value of the property

  • < Response > setReasonPhrase ( string reasonPhrase )

    Sets a custom HTTP Reason phrase

    Parameter Name Data Type Description
    reasonPhrase string Reason phrase value

  • < Response > setStatusCode ( int statusCode )

    Sets the HTTP status code of the response

    Parameter Name Data Type Description
    statusCode int HTTP status code

  • < Response > setStringPayload ( string payload )

    Sets a string as the response payload

    Parameter Name Data Type Description
    payload string The string payload to be set

  • < Response > setXmlPayload ( xml payload )

    Sets an XML as the response payload

    Parameter Name Data Type Description
    payload xml The XML payload object

public struct Session

Represents an HTTP Session

  • < Session > getAttribute ( string attributeKey ) ( any )

    Gets the named session attribute

    Parameter Name Data Type Description
    attributeKey string HTTP session attribute key

    Return Variable Data Type Description
    any

  • < Session > getAttributeNames ( ) ( string[] )

    Gets the session attribute names

    Return Variable Data Type Description
    string[]

  • < Session > getAttributes ( ) ( map )

    Gets the session attribute key value pairs as a map

    Return Variable Data Type Description
    map

  • < Session > getCreationTime ( ) ( int )

    Gets the session creation time

    Return Variable Data Type Description
    int

  • < Session > getId ( ) ( string )

    Gets the session cookie ID

    Return Variable Data Type Description
    string

  • < Session > getLastAccessedTime ( ) ( int )

    Gets the last time the sessions was accessed

    Return Variable Data Type Description
    int

  • < Session > getMaxInactiveInterval ( ) ( int )

    Gets maximum inactive interval for the session. The session expires after this time period.

    Return Variable Data Type Description
    int

  • < Session > invalidate ( )

    Invalidates the session and it will no longer be accessible from the request

  • < Session > isNew ( ) ( boolean )

    Checks whether the given session is a newly created session or an existing session

    Return Variable Data Type Description
    boolean

  • < Session > removeAttribute ( string attributeKey )

    Remove the named session attribute

    Parameter Name Data Type Description
    attributeKey string Session attribute key

  • < Session > setAttribute ( string attributeKey , any attributeValue )

    Sets the specified key/value pair as a session attribute

    Parameter Name Data Type Description
    attributeKey string Session attribute key
    attributeValue any Session attribute Value

  • < Session > setMaxInactiveInterval ( int timeInterval )

    Sets the maximum inactive interval for the session. The session expires after this time period.

    Parameter Name Data Type Description
    timeInterval int Session max inactive interval

public connector HttpClient ( string serviceUri , Options connectorOptions )

Http client connector for outbound HTTP requests

Parameter Name Data Type Description
serviceUri string Url of the service
connectorOptions Options connector options

Actions:

  • < HttpClient > delete ( string path , Request req ) ( Response , HttpConnectorError )

    The DELETE action implementation of the HTTP connector

    Parameter Name Data Type Description
    path string Resource path
    req Request An HTTP Request struct

    Return Variable Data Type Description
    Response
    HttpConnectorError

  • < HttpClient > execute ( string HTTPVerb , string path , Request req ) ( Response , HttpConnectorError )

    Invokes an HTTP call with the specified HTTP verb.

    Parameter Name Data Type Description
    HTTPVerb string HTTP verb value
    path string Resource path
    req Request An HTTP Request struct

    Return Variable Data Type Description
    Response
    HttpConnectorError

  • < HttpClient > forward ( string path , Request req ) ( Response , HttpConnectorError )

    forward action can be used to invoke an HTTP call with incoming request HTTPVerb

    Parameter Name Data Type Description
    path string Request path
    req Request An HTTP Request struct

    Return Variable Data Type Description
    Response
    HttpConnectorError

  • < HttpClient > get ( string path , Request req ) ( Response , HttpConnectorError )

    GET action implementation of the HTTP Connector

    Parameter Name Data Type Description
    path string Request path
    req Request An HTTP Request struct

    Return Variable Data Type Description
    Response
    HttpConnectorError

  • < HttpClient > head ( string path , Request req ) ( Response , HttpConnectorError )

    The HEAD action implementation of the HTTP Connector.

    Parameter Name Data Type Description
    path string Resource path
    req Request An HTTP Request struct

    Return Variable Data Type Description
    Response
    HttpConnectorError

  • < HttpClient > options ( string path , Request req ) ( Response , HttpConnectorError )

    OPTIONS action implementation of the HTTP Connector

    Parameter Name Data Type Description
    path string Request path
    req Request An HTTP Request struct

    Return Variable Data Type Description
    Response
    HttpConnectorError

  • < HttpClient > patch ( string path , Request req ) ( Response , HttpConnectorError )

    The PATCH action implementation of the HTTP Connector.

    Parameter Name Data Type Description
    path string Resource path
    req Request An HTTP Request struct

    Return Variable Data Type Description
    Response
    HttpConnectorError

  • < HttpClient > post ( string path , Request req ) ( Response , HttpConnectorError )

    The POST action implementation of the HTTP Connector.

    Parameter Name Data Type Description
    path string Resource path
    req Request An HTTP Request struct

    Return Variable Data Type Description
    Response
    HttpConnectorError

  • < HttpClient > put ( string path , Request req ) ( Response , HttpConnectorError )

    The PUT action implementation of the HTTP Connector.

    Parameter Name Data Type Description
    path string Resource path
    req Request An HTTP Request struct

    Return Variable Data Type Description
    Response
    HttpConnectorError

public annotation configuration

Configuration for HTTP service

Attribute Name Data Type Description
host string Host of the service
port int Port number of the service
httpsPort int HTTPS port number of service
basePath string Service base path
keyStoreFile string File path to keystore file
keyStorePassword string The keystore password
trustStoreFile string File path to truststore file
trustStorePassword string The truststore password
sslVerifyClient string The type of client certificate verification
certPassword string The certificate password
sslEnabledProtocols string SSL/TLS protocols to be enabled
ciphers string List of ciphers to be used
sslProtocol string The SSL protocol version
allowOrigins string[] The array of origins with which the response is shared by the service
allowCredentials boolean Specifies whether credentials are required to access the service
allowMethods string[] The array of allowed methods by the service
allowHeaders string[] The array of allowed headers by the service
maxAge int The maximum duration to cache the preflight from client side
exposeHeaders string[] The array of allowed headers which are exposed to the client
keepAlive boolean
transferEncoding string The types of encoding applied to the response
chunking string The chunking behaviour of the response
webSocket webSocket Annotation to define HTTP to WebSocket upgrade

public annotation resourceConfig

Configuration for HTTP resource

Attribute Name Data Type Description
methods string[] The array of allowed HTTP methods
path string The path of resource
consumes string[] The media types which are accepted by resource
produces string[] The media types which are produced by resource
allowOrigins string[] The array of origins with which the response is shared by the resource
allowCredentials boolean Specifies whether credentials are required to access the resource
allowMethods string[] The array of allowed methods by the resource
allowHeaders string[] The array of allowed headers by the resource
maxAge int The duration to cache the preflight from client side
exposeHeaders string[] The array of allowed headers which are exposed to the client

public annotation webSocket

Annotation to upgrade connection from HTTP to WS in the same base path.

Attribute Name Data Type Description
upgradePath string Upgrade path for the WebSocket service from HTTP to WS.
serviceName string Name of the WebSocket service where the HTTP service should upgrade to.